MCP Shopline

MCP商店线

](https://pypi.org/project/mcp-shopline/) ](https://pypi.org/project/mcp-shopline/)  ](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) 

繁体中文

开源 MCP（模型上下文协议） 包装的服务器 商店线开放API 将143个AI可调用工具（75个读取+68个写入）用于电子商务数据分析。

专为 克劳德代码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 参考

该项目建立在 商店线开放API v1.

• API文件：https://open-api.docs.shoplineapp.com
• 身份验证：通过Shopline商家管理员进行承载令牌
• 基本URL: https://open.shopline.io/v1/

您需要来自Shopline商家帐户的有效Shopline API访问令牌。请参阅 车间API认证指南 如何获得一个。

______________________________________________________________________

快速开始

安装

pip install mcp-shopline

或者使用uvx（无需安装）：

uvx --from mcp-shopline mcp-shopline

设置API令牌：

export SHOPLINE_API_TOKEN=your_token_here

与Claude Code一起使用

通过Claude CLI添加服务器：

claude mcp add --transport stdio shopline -- mcp-shopline

或者将环境变量内联：

claude mcp add --transport stdio shopline -e SHOPLINE_API_TOKEN=your_token_here -- mcp-shopline

如果你在本地克隆仓库 .mcp.json Claude Code将自动检测配置，所有143个工具将立即可用。

与Claude Desktop一起使用

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "shopline": {
      "command": "mcp-shopline",
      "env": {
        "SHOPLINE_API_TOKEN": "your_token_here"
      }
    }
  }
}

或者使用uvx：

{
  "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）

产品与库存（9）

分析（11）

客户（9）

分类与促销（14）

订单延期（8）

商店设置（12）

______________________________________________________________________

书写工具（68）

书写工具标有 [WRITE] 在他们的描述中。它们需要适当的令牌权限和 SHOPLINE_TEST_WRITES=1 在测试中运行。

______________________________________________________________________

API端点覆盖率

基于 商店线开放API v1:

注： 端点可用性取决于您的Shopline API令牌权限。上述状态反映了完全权限访问。将您的令牌限制在您需要的范围内。

______________________________________________________________________

项目结构

mcp-shopline/
├── mcp_server.py              # MCP Server (stdio JSON-RPC 2.0)
├── .mcp.json                  # Claude Code MCP auto-discovery config
├── .env.example               # Environment variable template
├── config/
│   └── settings.py            # API config (token from env, endpoints)
├── tools/
│   ├── base_tool.py           # Shared HTTP client (retry, pagination)
│   ├── order_tools.py         # Order read tools (12)
│   ├── product_tools.py       # Product/inventory read tools (9)
│   ├── analytics_tools.py     # Analytics read tools (11)
│   ├── customer_tools.py      # Customer read tools (9)
│   ├── category_tools.py      # Category & promotion read tools (14)
│   ├── extended_tools.py      # Order extended read tools (8)
│   ├── settings_tools.py      # Store settings read tools (12)
│   ├── writes/
│   │   ├── order_writes.py    # Order write tools (8)
│   │   ├── customer_writes.py # Customer write tools (6)
│   │   ├── product_writes.py  # Product write tools (15)
│   │   ├── promotion_writes.py # Promotion/coupon write tools (12)
│   │   ├── category_writes.py # Category write tools (3)
│   │   ├── return_writes.py   # Return order write tools (2)
│   │   ├── conversation_writes.py # Conversation write tools (2)
│   │   ├── review_writes.py   # Review write tools (6)
│   │   ├── gift_writes.py     # Gift/addon write tools (7)
│   │   ├── purchase_writes.py # Purchase order write tools (2)
│   │   ├── media_writes.py    # Media/metafield write tools (2)
│   │   └── delivery_writes.py # Delivery/merchant write tools (3)
│   └── tool_registry.py       # Unified tool registry
├── tests/
│   └── test_all_tools.py      # E2E tests for all 143 tools
└── scripts/
    ├── auth/
    │   ├── test_connection.py     # API connection validator
    │   └── inspect_data_structure.py  # API response structure explorer
    └── audit/
        └── scope_check.py     # Token scope and permission auditor

API约束

这些是由工具内部处理的Shopline Open API限制：

• 分页: page + per_page （最大50），页面之间0.2秒的延迟用于速率限制
• 搜索限制：最多10000个结果； fetch_all_pages_by_date_segments() 按日期范围拆分大型查询
• 订单状态：在线订单使用 confirmed，POS使用 completed --默认情况下，这两种工具都包括在内
• 通道标识: created_from = "shop" 在线的 "pos" （零售）；店铺名称来自 order.channel.created_by_channel_name
• 货币：所有货币价值以TWD（新台湾元）为单位，通过 money_to_float()

______________________________________________________________________

发展

从源安装

git clone https://github.com/asgard-ai-platform/mcp-shopline.git
cd mcp-shopline
pip install -e .

运行测试

# Read tools (no side effects)
python tests/test_all_tools.py

# Include write tools (creates/updates/deletes data)
SHOPLINE_TEST_WRITES=1 python tests/test_all_tools.py

python scripts/auth/test_connection.py

添加新工具

1. 定义模式dict（Claude API tool_use 格式与 name, description, input_schema)
2. 使用实现该功能 api_get / fetch_all_pages 从 base_tool.py
3. 追加 {"schema": ..., "function": ...} 到模块的工具列表
4. 通过自动注册 tool_registry.py 和 mcp_server.py --无需额外布线

______________________________________________________________________

已知测试差距

以下工具已实施并注册，但 未经过全面的E2E测试 由于测试存储数据或令牌范围的限制。它们正确编译、成功导入并遵循所有项目约定——它们只需要真实数据或更广泛的令牌权限来进行端到端验证。

需要商店数据（通过Shopline管理员创建）

需要令牌权限

编写工具

所有68个写入工具都已在导入/注册级别进行了验证。完整的E2E写入测试需要 SHOPLINE_TEST_WRITES=1 以及一个专用的测试存储，以避免修改生产数据。看 tests/test_writes/ 用于门控测试脚本。

路线图

• \[x\] get_refund_by_store --按商店/渠道细分的退货订单
• \[x\] get_stock_transfer_suggestions --根据销售速度和库存水平自动生成仓库间转移建议
• \[x\] get_category_tree --独立类别结构查看器
• \[x\] get_promotion_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）需要挽回。

______________________________________________________________________

“创建新客户”（编写工具）

你： 帮我建立一个新客户，姓名王小明，email wang@test.com

AI呼叫：

create_customer(
  name = "王小明",
  email = "wang@test.com"
)

结果： [WRITE] 客户王小明建立成功，ID: 69d77d57...

______________________________________________________________________

贡献

欢迎投稿！请打开问题或提交拉取请求。

添加新工具时，请遵循中的现有模式 tools/ 并确保该工具通过E2E测试套件。

许可证

麻省理工学院