sellercloud-mcp

首个用于 SellerCloud 的模型上下文协议 (MCP) 服务器。在五分钟内将 Claude 连接到您的目录、库存、订单和渠道列表 — 仅限只读。

为什么存在这个项目

SellerCloud 没有公开的 SDK。他们的 REST API 文档齐全但没有品牌化 —— 每个针对它进行自动化的团队最终都在重复编写相同的身份验证和分页代码。

如果您使用 Claude（或任何支持 MCP 的 AI 助手）进行日常电商运营，这个差距就是“总结今天的订单”开箱即用与“总结今天的订单”需要自定义集成之间的区别。

sellercloud-mcp 弥补了这一差距。它是一个小巧、经过充分测试、采用 MIT 许可的 MCP 服务器，向任何 MCP 客户端公开了七个只读的 SellerCloud 端点。它建立在多年大规模电商自动化运营的经验之上。

Related MCP server: Amazon Marketplace MCP Server by CData

您可以用它做什么

将此服务器连接到 Claude Code、Claude Desktop 或任何 MCP 主机，然后询问如下问题：

• “搜索任何包含 WIDGET 的 SKU，并向我展示库存水平。”

• “我们昨天在所有市场上总共发货了多少订单？按渠道分组。”

• “拉取订单 100001 并告诉我哪些行项目已发货。”

• “列出为公司 9001 配置的渠道，并显示哪些是活动的。”

• “对于 SKU ACME-001，比较每个渠道列表中的价格。”

Claude 直接读取您的目录。无需复制粘贴，无需电子表格，无需自定义管道。

工具 (v0.1，均为只读)

写入端点（创建订单、更新库存、推送渠道更改）在 v0.1 中特意未包含。它们计划在 v0.2 中实现，待只读功能稳定后推出。

pip install sellercloud-mcp

v0.1 从此存储库发布。PyPI 发布正在进行中 —— 目前，请使用 pip install git+https://github.com/alveyautomation/sellercloud-mcp 安装，或在本地克隆并运行 pip install -e .。

配置凭据

服务器从环境变量中读取所有内容。将 .env.example 复制到 .env 并填写您的租户信息：

SELLERCLOUD_API_URL=https://your-team.api.sellercloud.com/rest/
SELLERCLOUD_USERNAME=your-username
SELLERCLOUD_PASSWORD=your-password
SELLERCLOUD_DEFAULT_COMPANY_ID=        # optional fallback
SELLERCLOUD_HTTP_TIMEOUT=60            # optional, seconds
SELLERCLOUD_MAX_RETRIES=3              # optional

请使用只读的 SellerCloud 账户。 v0.1 仅调用 GET 端点，但纵深防御意味着您应该为服务器提供一个无法修改任何内容的专用用户。当 v0.2 推出写入工具时，通过升级凭据来选择加入 —— 切勿反向操作。

连接到 Claude Code

添加到 ~/.claude/claude_code_config.json（或您项目的 MCP 配置）：

{
  "mcpServers": {
    "sellercloud": {
      "command": "sellercloud-mcp",
      "env": {
        "SELLERCLOUD_API_URL": "https://your-team.api.sellercloud.com/rest/",
        "SELLERCLOUD_USERNAME": "your-username",
        "SELLERCLOUD_PASSWORD": "your-password",
        "SELLERCLOUD_DEFAULT_COMPANY_ID": "9001"
      }
    }
  }
}

重启 Claude Code。七个 sellercloud_* 工具将出现在任何新会话中。

连接到 Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 或 %APPDATA%\Claude\claude_desktop_config.json (Windows)，并添加与上述相同的 mcpServers 块。重启桌面应用程序。

工具参考

每个工具都返回一个 JSON 信封：

{ "ok": true,  "data": { ... } }
{ "ok": false, "error": "human-readable message" }

sellercloud_search_products

sellercloud_search_products(
    query: str,                          # required
    company_id: int | None = None,       # falls back to default if unset
    page: int = 1,
    page_size: int = 50,                 # capped at 50 by SellerCloud
)

示例响应：

{
  "ok": true,
  "data": {
    "items": [
      { "ID": "ACME-WIDGET-001", "ProductName": "Acme Widget, Standard", "Price": 29.99 }
    ],
    "total": 1,
    "page": 1,
    "page_size": 50
  }
}

sellercloud_get_product

sellercloud_get_product(sku: str, company_id: int | None = None)

返回目录记录，如果 SKU 不在公司的目录中，则返回 data: null。

sellercloud_search_orders

sellercloud_search_orders(
    date_from: str,                      # ISO date "YYYY-MM-DD"
    date_to: str,                        # ISO date "YYYY-MM-DD"
    company_id: int | None = None,
    query: str | None = None,
    limit: int = 200,                    # max 1000
)

分页处理是透明的 —— SellerCloud 将页面大小限制为 50，但该工具会收集最多 limit 的页面。当订单数量超过 limit 允许的数量时，响应包含 limit_reached: true。

sellercloud_get_order

sellercloud_get_order(order_id: int)

返回完整的订单记录（包含 Items[]），如果 404 则返回 data: null。

sellercloud_get_inventory

sellercloud_get_inventory(sku: str, company_id: int | None = None)

返回的记录包括：

• InventoryAvailableQty —— API 目前认为可销售的数量

• PhysicalQty —— 现有数量

• ReservedQty —— 为未结订单保留的数量

• OnOrder —— 进货 PO 数量

使用 InventoryAvailableQty 作为规范的“我可以销售的数量”。

sellercloud_list_channels

sellercloud_list_channels(company_id: int | None = None)

返回公司已配置的渠道订阅源列表。每条记录包括 ChannelID、Name 和 Active。

sellercloud_get_channel_listing

sellercloud_get_channel_listing(channel_id: int, sku: str)

各渠道列表详情。对于跨市场抽查价格非常有用。

本地开发

git clone https://github.com/alveyautomation/sellercloud-mcp
cd sellercloud-mcp
python -m venv .venv && source .venv/bin/activate    # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pytest                                                # 44 tests, ~4s

预提交钩子（gitleaks、ruff、格式化程序、租户指纹清理器）：

pip install pre-commit
pre-commit install

针对真实 SellerCloud 沙盒账户的集成测试受 SELLERCLOUD_INTEGRATION_TESTS=1 保护。正常贡献不需要这些测试。

故障排除

Failed to obtain SellerCloud token —— 用户名/密码被拒绝。最常见的原因：账户启用了 2FA 或被锁定。SellerCloud 的 POST /api/token 端点需要一个非 2FA 的服务账户。

Missing required environment variables —— 服务器在加载 .env 之前尝试启动。请在父 shell 中导出变量，或确保您的 MCP 主机配置在 env 块中包含了它们。

尽管有已知数据但结果为空 —— 确认 company_id 是否正确。除非您明确传递 companyID，否则 SellerCloud 仅返回经过身份验证的用户的默认公司。

分页感觉很慢 —— 页面大小由 SellerCloud 限制为 50，而不是由我们限制。对于较大的日期范围，预计会有多次往返请求。

贡献

欢迎提交问题和拉取请求。请：

• 在打开 PR 之前运行 pytest (pip install -e ".[dev]")。

• 运行 pre-commit run --all-files。

• 将 v0.1 的新增内容保持在只读范围内。写入端点将在 v0.2 中推出。

• 测试中仅使用合成数据 —— 不得包含真实的 SKU、客户名称或订单号。

许可证

MIT —— 参见 LICENSE。

免责声明

sellercloud-mcp 是一个非官方的第三方集成。它未得到 SellerCloud, Inc. 的认可、关联或支持。 “SellerCloud” 是 SellerCloud, Inc. 的商标。使用风险自负；在依赖它进行生产决策之前，请针对您的租户验证其行为。