Cin7 Omni MCP Server

一个 MCP 服务器，让 Claude 能够完全访问 Cin7 Omni API——API 支持的每一个资源和每一个操作：

Contacts · Branches · Product Categories · Products · Product Options · Product Images · Size Ranges · Stock · Serial Numbers · Branch Transfers · Adjustments · Vouchers · Sales Orders (incl. cartons) · Payments · Payment Fees & Payouts · Purchase Orders · Quotes · Credit Notes · BOM Masters (v1 & v2) · Production Jobs · Users · Cartons

动词矩阵（哪些资源可以被列出、获取、创建、更新或删除）取自 Cin7 官方 swagger 规范，并由服务器强制执行，因此 Claude 永远不会尝试 API 不支持的操作。

工具

读取和写入是分开的工具，带有正确的 MCP 注解（readOnlyHint、destructiveHint），因此在 Claude 中，你可以独立于读取操作，将每个写入工具设置为始终允许、每次询问或拒绝。

Related MCP server: GHL MCP Server

在 Claude Desktop 中安装（3 步，无需编辑配置）

1. 获取你的 Cin7 API 凭据 —— 在 Cin7 Omni 中：Settings (⚙) → Integrations → API v1 → Add API Connection。这会为你提供 API Username 和 API Key（Basic-auth 凭据，不是你的 Cin7 登录信息）。为你希望 Claude 访问的模块授予该连接的权限——没有权限的模块会返回 403。

2. 下载 dist/cin7-omni.mcpb —— 一个文件，约 150 KB。

3. 打开它 —— 双击该文件（或在 Claude Desktop 中：Settings → Extensions → 将文件拖入），然后点击 Install。在提示时粘贴 API Username 和 API Key；密钥存储在你电脑的钥匙串中，绝不会保存在文件里。还有一个 Read-only mode 开关，如果你希望将 Claude 锁定为仅查询。

然后让 Claude 做类似 "describe the Cin7 SalesOrders resource" 的操作，以确认它正常工作。

之后要移除它：Claude Desktop → Settings → Extensions → Cin7 Omni → Uninstall。

其他运行方式

仓库中还附带了一个预构建、自包含的服务器（dist/index.js —— 所有依赖都已打包在内），因此克隆仓库就足以运行它：无需 npm install，无需构建步骤。git pull 总能让你获得最新的、可随时测试的构建版本。

git clone https://github.com/panagiotis1226/cin7-omni-mcp.git

只有当你自行修改源码时：运行 npm install（会自动构建）或 npm run build 重新构建。

Claude Code：

claude mcp add cin7-omni \
  -e CIN7_API_USERNAME=YourApiUsername \
  -e CIN7_API_KEY=your-api-key \
  -- node /absolute/path/to/cin7-omni-mcp/dist/index.js

Claude Desktop（手动配置） —— 添加到 claude_desktop_config.json（Settings → Developer → Edit Config）：

{
  "mcpServers": {
    "cin7-omni": {
      "command": "node",
      "args": ["/absolute/path/to/cin7-omni-mcp/dist/index.js"],
      "env": {
        "CIN7_API_USERNAME": "YourApiUsername",
        "CIN7_API_KEY": "your-api-key"
      }
    }
  }
}

环境变量

控制写入权限

两层机制：

1. Claude 的按工具权限 —— 当 Claude 首次调用 cin7_create、cin7_update、cin7_delete 或 cin7_upload_product_image 时，系统会提示你，并且你可以按工具选择允许一次、始终允许或拒绝（在 Claude Code 中，可在 /permissions 下管理这些权限）。

2. 服务端硬锁定 —— 设置 CIN7_READ_ONLY=true，写入工具将完全不会被注册。

速率限制

Cin7 强制执行每秒 3 次、每分钟 60 次、每天 5,000 次的调用限制。服务器在客户端对请求进行排队，以保持在每秒/每分钟限制之内，并在 429/5xx 时自动退避重试，因此大型多页扫描按设计就是缓慢的。使用 where 筛选（例如 modifiedDate>='...'）和 fields 参数，以尽量减少调用。

示例提示

• "CTS001 在各个 Branch 的库存是多少？" → 对 Stock 执行 cin7_list，使用 where: "code='CTS001'"

• "显示本周发货且超过 500 美元的销售订单" → 对 SalesOrders 执行 cin7_list，带上 where 筛选

• "为供应商 X 创建包含这些行项目的采购订单……" → 先对 PurchaseOrders 执行 cin7_describe，再执行 cin7_create

• "Contact 有哪些字段？" → 对 Contacts 执行 cin7_describe

开发

npm test           # builds, then runs the stdio smoke test against a mock Cin7 API
npm run build:mcpb # rebuild + validate manifest + repack dist/cin7-omni.mcpb
npm run dev        # run from source with tsx

构建会从同一份源码生成两个包：dist/index.js（ESM，用于克隆即运行 / Claude Code）和 server/index.cjs（CJS，打包进 .mcpb 扩展中）。

src/fieldReference.ts 由 scripts/gen_fields.py 从 Cin7 官方 swagger 规范生成（该脚本期望工作目录中存在来自 https://api.cin7.com/api/swagger/v1/swagger.json 的 swagger.json）——如果 Cin7 更新其 API，请重新生成。

未涵盖的内容

• Cin7 Omni webhooks（推送通知）——此服务器仅支持请求/响应模式。

• Cin7 未通过 v1/v2 API 暴露的任何内容。

• 远程/HTTP 部署——这是一个本地 stdio 服务器；将来可以添加 streamable-HTTP 入口。