内容
# MCP Shopline
[](https://pypi.org/project/mcp-shopline/)
[](https://pypi.org/project/mcp-shopline/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/asgard-ai-platform/mcp-shopline/stargazers)
[](https://github.com/asgard-ai-platform/mcp-shopline/issues)
[](https://github.com/asgard-ai-platform/mcp-shopline/commits/main)
[](https://modelcontextprotocol.io/)
[繁體中文](README.zh-TW.md)
一个开源的 [MCP（模型上下文协议）](https://modelcontextprotocol.io/) 服务器，封装了 [Shopline 开放 API](https://open-api.docs.shoplineapp.com/docs/getting-started)，提供 143 个 AI 可调用的工具（75 个读取 + 68 个写入），用于电子商务数据分析。
适用于 [Claude Code](https://claude.ai/code)、Claude Cowork 和任何 MCP 兼容的 AI 客户端。使 AI 代理能够通过自然语言查询 Shopline 商店的订单、产品、库存、客户行为和促销活动。
## 功能
- **143 个现成的工具**，涵盖订单、产品、库存、客户、促销、类别、订阅、对话、评论等
- **MCP 服务器**（stdio JSON-RPC 2.0）— 插入 Claude Code，立即开始提问
- **零外部依赖**，仅需 Python 3.9+ 标准库和 `requests`
- **内置分页、重试和速率限制** — 工具内部处理所有 API 复杂度
- **为 AI 代理设计** — 结构化 JSON 输出，参数支持自然语言（日期为 `YYYY-MM-DD`，而非时间戳）
## API 参考
本项目基于 [Shopline 开放 API v1](https://open-api.docs.shoplineapp.com/docs/getting-started)。
- API 文档：https://open-api.docs.shoplineapp.com
- 认证：通过 Shopline 商户管理员使用 Bearer Token
- 基础 URL：`https://open.shopline.io/v1/`
您需要从 Shopline 商户账户获取有效的 Shopline API 访问令牌。请参阅 [Shopline API 认证指南](https://open-api.docs.shoplineapp.com/docs/authentication) 以了解如何获取。
---
## 快速开始
### 安装
```bash
pip install mcp-shopline
```
或使用 uvx（无需安装）：
```bash
uvx --from mcp-shopline mcp-shopline
```
设置您的 API 令牌：
```bash
export SHOPLINE_API_TOKEN=your_token_here
```
### 与 Claude Code 结合使用
通过 Claude CLI 添加服务器：
```bash
claude mcp add --transport stdio shopline -- mcp-shopline
```
或在环境变量中内联：
```bash
claude mcp add --transport stdio shopline -e SHOPLINE_API_TOKEN=your_token_here -- mcp-shopline
```
如果您在本地克隆了仓库，Claude Code 将自动检测 `.mcp.json` 配置文件，所有 143 个工具立即可用。
### 与 Claude 桌面版结合使用
添加到您的 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"shopline": {
"command": "mcp-shopline",
"env": {
"SHOPLINE_API_TOKEN": "your_token_here"
}
}
}
}
```
或使用 uvx：
```json
{
"mcpServers": {
"shopline": {
"command": "uvx",
"args": ["--from", "mcp-shopline", "mcp-shopline"],
"env": {
"SHOPLINE_API_TOKEN": "your_token_here"
}
}
}
}
```
---
## 重要：写入工具
此服务器包含 **创建、更新和删除** Shopline 商店数据的工具。
您的 API 令牌的权限范围控制哪些操作可用。
- 在 Shopline 商户管理员中查看令牌权限
- 限制为仅所需的范围
- 写入工具在描述中明确标记为 `[WRITE]` 前缀
- 写入测试需要 `SHOPLINE_TEST_WRITES=1` 运行
---
## 工具（143 个）
### 读取工具（75 个）
#### 订单（12 个）
| 工具 | 描述 |
|------|-------------|
| `query_orders` | 按日期、状态、渠道、商店查询订单 |
| `get_sales_summary` | 收入、AOV、商品价格、支付/配送明细 |
| `get_top_products` | 按数量或收入排名的产品销售 |
| `get_sales_trend` | 每日/每周/每月销售趋势数据 |
| `get_channel_comparison` | 跨商店/渠道比较性能 |
| `get_order_detail` | 完整的订单详情，包含商品 |
| `get_refund_summary` | 退货订单统计和退款金额 |
| `get_archived_orders` | 查询归档/关闭的订单 |
| `get_order_labels` | 订单附带的标签列表 |
| `get_order_tags` | 订单附带的标签列表 |
| `get_order_action_logs` | 订单的操作/审计日志 |
| `get_order_transactions` | 订单的支付交易记录 |
#### 产品和库存（9 个）
| 工具 | 描述 |
|------|-------------|
| `get_product_list` | 按关键词、品牌搜索产品 |
| `get_product_variants` | SKU 变体的尺寸 x 颜色矩阵 |
| `get_inventory_overview` | 按品牌划分的库存总览 |
| `get_low_stock_alerts` | 低库存/缺货 SKU 警报 |
| `get_warehouses` | 列出所有仓库和商店位置 |
| `get_stock_by_warehouse` | 每个仓库的库存分布矩阵 |
| `get_locked_inventory` | 查看被待处理订单锁定的库存 |
| `list_purchase_orders` | 列出采购/补货订单 |
| `get_purchase_order_detail` | 单个采购订单的完整详情 |
#### 分析（11 个）
| 工具 | 描述 |
|------|-------------|
| `get_rfm_analysis` | 客户 RFM 分段 |
| `get_repurchase_analysis` | 重复购买率和周期分析 |
| `get_customer_geo_analysis` | 客户地理分布 |
| `get_inventory_turnover` | 库存周转率和天数 |
| `get_category_sales` | 按产品类别划分的销售情况 |
| `get_promotion_analysis` | 促销活动效果分析 |
| `get_refund_by_store` | 按商店/渠道划分的退货订单情况 |
| `get_stock_transfer_suggestions` | 自动生成仓库间转移建议 |
| `get_promotion_roi` | 促销期间与销售趋势交叉分析，计算提升和 ROI |
| `get_customer_lifecycle` | 比较两个时间段的 RFM 分段，跟踪客户迁移 |
| `get_slow_movers` | 确定高库存但销售低的产品，为清仓计划提供参考 |
#### 客户（9 个）
| 工具 | 描述 |
|------|-------------|
| `list_customers` | 搜索和列出客户资料 |
| `get_customer_profile` | 单个客户的完整资料 |
| `list_customer_groups` | 列出客户分段群体 |
| `get_customer_group_members` | 群体内的成员 |
| `list_store_credits` | 商店积分余额和历史记录 |
| `list_membership_tiers` | 会员级别定义 |
| `get_customer_tier_history` | 客户级别升级/降级历史 |
| `list_member_point_rules` | 积分赚取和兑换规则 |
| `list_custom_fields` | 客户资料的自定义字段定义 |
#### 类别和促销（14 个）
| 工具 | 描述 |
|------|-------------|
| `get_category_tree` | 完整的类别层次树 |
| `get_category_detail` | 单个类别的详情 |
| `list_promotions` | 列出所有促销活动 |
| `get_promotion_detail` | 单个促销活动的完整详情 |
| `search_promotions` | 按关键词或状态搜索促销活动 |
| `list_flash_price_campaigns` | 列出闪购/限时价格活动 |
| `get_flash_price_campaign_detail` | 单个闪购活动的详情 |
| `list_affiliate_campaigns` | 列出联盟营销活动 |
| `get_affiliate_campaign_detail` | 单个联盟活动的详情 |
| `get_affiliate_campaign_usage` | 联盟活动的用量和性能统计 |
| `list_gifts` | 列出购买赠品活动 |
| `list_addon_products` | 列出附加产品活动 |
| `list_product_subscriptions` | 列出产品订阅计划 |
| `get_product_subscription_detail` | 单个订阅计划的详情 |
#### 订单扩展（8 个）
| 工具 | 描述 |
|------|-------------|
| `list_return_orders` | 列出退货订单 |
| `get_return_order_detail` | 单个退货订单的完整详情 |
| `get_order_delivery` | 订单的配送跟踪和物流信息 |
| `list_conversations` | 列出客户服务对话 |
| `get_conversation_messages` | 对话线程中的消息 |
| `list_product_reviews` | 列出产品评论 |
| `get_product_review_detail` | 单个产品评论的完整详情 |
#### 商店设置（12 个）
| 工具 | 描述 |
|------|-------------|
| `list_merchants` | 列出商户账户 |
| `get_merchant_detail` | 单个商户的详情 |
| `list_payments` | 列出配置的支付方式 |
| `list_delivery_options` | 列出配置的配送选项 |
| `get_delivery_option_detail` | 单个配送选项的详情 |
| `get_delivery_time_slots` | 可用的配送时间段 |
| `list_channels` | 列出销售渠道（在线、POS 等） |
| `get_channel_detail` | 单个渠道的详情 |
| `get_app_settings` | 应用级别的配置设置 |
| `list_taxes` | 列出税务配置 |
| `get_staff_permissions` | 员工账户权限设置 |
| `get_token_info` | 当前 API 令牌的信息和范围 |
| `list_agents` | 列出客户服务代理账户 |
---
### 写入工具（68 个）
写入工具在描述中以 `[WRITE]` 为前缀。它们需要适当的令牌权限和 `SHOPLINE_TEST_WRITES=1` 才能在测试中运行。
| 领域 | 工具 |
|--------|-------|
| 订单操作 | 8 个工具 — 更新状态、添加备注、分配标签/标签、取消、履行 |
| 客户操作 | 6 个工具 — 创建/更新客户、调整商店积分、更新群体成员 |
| 产品操作 | 15 个工具 — 创建/更新/删除产品、管理变体、更新库存 |
| 促销/优惠/活动操作 | 12 个工具 — 创建/更新/删除促销、优惠、闪购、联盟活动 |
| 类别操作 | 3 个工具 — 创建、更新、删除类别 |
| 退货订单操作 | 2 个工具 — 批准/拒绝退货订单 |
| 对话操作 | 2 个工具 — 回复对话、更新对话状态 |
| 评论操作 | 6 个工具 — 回复评论、批准/拒绝/隐藏评论 |
| 赠品/附加操作 | 7 个工具 — 创建/更新/删除赠品和附加活动 |
| 采购订单操作 | 2 个工具 — 创建和接收采购订单 |
| 媒体/元字段操作 | 2 个工具 — 上传媒体、设置元字段 |
| 配送/商户操作 | 3 个工具 — 更新配送信息、管理商户设置 |
---
## API 端点覆盖
基于 [Shopline 开放 API v1](https://open-api.docs.shoplineapp.com/docs/getting-started)：
| 端点 | 状态 | 备注 |
|----------|--------|-------|
| [订单](https://open-api.docs.shoplineapp.com/docs/order) | 200 | 完整访问（读取 + 写入） |
| [产品](https://open-api.docs.shoplineapp.com/docs/product) | 200 | 完整访问（读取 + 写入） |
| [仓库](https://open-api.docs.shoplineapp.com/docs/warehouse) | 200 | 完整访问 |
| [类别](https://open-api.docs.shoplineapp.com/docs/category) | 200 | 完整访问（读取 + 写入） |
| [退货订单](https://open-api.docs.shoplineapp.com/docs/return-order) | 200 | 完整访问（读取 + 写入） |
| [促销](https://open-api.docs.shoplineapp.com/docs/promotion) | 200 | 完整访问（读取 + 写入） |
| [产品库存](https://open-api.docs.shoplineapp.com/docs/product-stock) | 200 | 按仓库划分的明细 |
| [客户](https://open-api.docs.shoplineapp.com/docs/customer) | 200 | 完整访问（读取 + 写入） |
| 渠道 | 200 | 完整访问 |
| 对话 | 200 | 客户服务线程（读取 + 写入） |
| 评论 | 200 | 产品评论（读取 + 写入） |
| 订阅 | 200 | 产品订阅计划 |
| 联盟活动 | 200 | 联盟营销（读取 + 写入） |
| 闪购活动 | 200 | 闪购（读取 + 写入） |
| 采购订单 | 200 | 补货订单（读取 + 写入） |
| 赠品 & 附加 | 200 | 购买赠品活动（读取 + 写入） |
| 商店设置 | 200 | 支付、配送、税务、员工权限 |
> **注意：** 端点可用性取决于您的 Shopline API 令牌权限。上述状态反映了完整权限访问。限制令牌仅限于您需要的范围。
---
## 项目结构```
mcp-shopline/
├── mcp_server.py # MCP 服务器（stdio JSON-RPC 2.0）
├── .mcp.json # Claude Code MCP 自动发现配置
├── .env.example # 环境变量模板
├── config/
│ └── settings.py # API 配置（令牌来自 env、端点）
├── tools/
│ ├── base_tool.py # 共享 HTTP 客户端（重试、分页）
│ ├── order_tools.py # 订单读取工具（12）
│ ├── product_tools.py # 产品/库存读取工具（9）
│ ├── analytics_tools.py # 分析读取工具（11）
│ ├── customer_tools.py # 客户读取工具（9）
│ ├── category_tools.py # 类别和促销读取工具（14）
│ ├── extended_tools.py # 订单扩展读取工具（8）
│ ├── settings_tools.py # 商店设置读取工具（12）
│ ├── writes/
│ │ ├── order_writes.py # 订单写入工具（8）
│ │ ├── customer_writes.py # 客户写入工具（6）
│ │ ├── product_writes.py # 产品写入工具（15）
│ │ ├── promotion_writes.py # 促销/优惠写入工具（12）
│ │ ├── category_writes.py # 类别写入工具（3）
│ │ ├── return_writes.py # 退货订单写入工具（2）
│ │ ├── conversation_writes.py # 对话写入工具（2）
│ │ ├── review_writes.py # 评论写入工具（6）
│ │ ├── gift_writes.py # 赠品/附加写入工具（7）
│ │ ├── purchase_writes.py # 采购订单写入工具（2）
│ │ ├── media_writes.py # 媒体/元字段写入工具（2）
│ │ └── delivery_writes.py # 配送/商户写入工具（3）
│ └── tool_registry.py # 统一工具注册表
├── tests/
│ └── test_all_tools.py # 所有 143 个工具的 E2E 测试
└── scripts/
├── auth/
│ ├── test_connection.py # API 连接验证器
│ └── inspect_data_structure.py # API 响应结构探索器
└── audit/
└── scope_check.py # 令牌范围和权限审计器
```
## API 约束
这些是 Shopline 开放 API 限制，由工具内部处理：
- **分页**：`page` + `per_page`（最大 50），每页 0.2s 延迟以限制速率
- **搜索限制**：10,000 个结果最大；`fetch_all_pages_by_date_segments()` 按日期范围拆分段大搜
- **订单状态**：在线订单使用 `confirmed`，POS 使用 `completed` — 工具默认包含两者
- **渠道识别**：`created_from` = `"shop"`（在线）/ `"pos"`（零售）；商店名称来自 `order.channel.created_by_channel_name`
- **货币**：所有货币价值以 TWD（新台币）表示，通过 `money_to_float()` 以浮点数返回
## 路线图
- [x] `get_refund_by_store` — 按店铺/渠道返回订单明细
- [x] `get_stock_transfer_suggestions` — 根据销售速度和库存水平自动生成仓库间转移建议
- [x] `get_category_tree` — 独立的类目结构查看器
- [x] `get_promotion_roi` — 将促销期与销售趋势数据进行交叉引用以计算提振和ROI
- [x] `get_customer_lifecycle` — 比较两个时间段的RFM分段以跟踪客户迁移（升级/流失）
- [x] `get_slow_movers` — 确定高库存但低销售的产品以进行清仓规划
- [x] 客户API工具（会员资料、人口统计、会员等级）
- [ ] 支持多个Shopline店铺（多令牌）
- [ ] 添加Webhook支持以实现实时订单通知
---
## 使用示例
### "这个月的销售情况如何？"
> **您：** 这个月的销售摘要是什么？
**AI调用：**
```
get_sales_summary(
start_date = "2026-04-01",
end_date = "2026-04-09",
channel = "all"
)
```
**结果：** 本月营业额 NT$1,234,567，共 456 笔订单，客单价 NT$2,707，线上占 62%、门市占 38%。
---
### "哪些产品最畅销？"
> **您：** 上个月最畅销的前 5 名商品是什么？
**AI调用：**
```
get_top_products(
start_date = "2026-03-01",
end_date = "2026-03-31",
top_n = 5,
sort_by = "revenue"
)
```
**结果：** 第一名「经典帆布休闲鞋 Classic Canvas」营收 NT$892,000（268 双），第二名「轻量機能防风外套」营收 NT$654,000...
---
### "告诉我关于这个客户"
> **您：** 帮我查一下客户「陈大明」的完整资讯
**AI调用：**
```
list_customers(search_keyword = "陈大明")
→ get_customer_profile(customer_id = "5f3a8b2c...")
```
**结果：** 陈大明，VIP 会员，累计消费 NT$56,330，近 30 天消费 5 次，会员点数余额 2,800 点，储值金余额 NT$500。
---
### "有哪些产品库存快要不足了？"
> **您：** 哪些商品快缺货了？
**AI调用：**
```
get_low_stock_alerts(threshold = 5)
```
**结果：** 共 3,098 个 SKU 低于门槛，其中 2,847 个已完全缺货。最严重的是「经典帆布休闲鞋 Classic Canvas」深蓝色 M 号（库存 0）。
---
### "比较线上和线下业绩"
> **您：** 比较一下线上和门市这个月的业绩
**AI调用：**
```
get_channel_comparison(
start_date = "2026-04-01",
end_date = "2026-04-09"
)
```
**结果：** 线上官网营收 NT$780,000（占 63%），信义旗舰店 NT$220,000（占 18%），中山概念店 NT$120,000（占 10%）...
---
### "谁是我的最佳客户和流失客户？"
> **您：** 分析一下客户 RFM 分群
**AI调用：**
```
get_rfm_analysis(
start_date = "2026-01-01",
end_date = "2026-04-09"
)
```
**结果：** 共 1,618 位客户。最佳客户 70 人（HHH），近期新客 433 人（HLL），流失高消费客户 188 人（LLH）需要挽回。
---
### "创建一个新客户" (Write tool)
> **您：** 帮我建立一个新客户，姓名王小明，email wang@test.com
**AI调用：**
```
create_customer(
name = "王小明",
email = "wang@test.com"
)
```
**结果：** `[WRITE]` 客户王小明建立成功，ID: 69d77d57...
---
## 贡献
欢迎贡献！请开启一个问题或提交拉取请求。
添加新工具时，请遵循 `tools/` 中的现有模式，并确保工具通过端到端测试套件。
## 许可证
MIT
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器