baselinker-mcp

一个 MCP 服务器，将整个 BaseLinker API —— 订单、发票、退货、快递、CRM、仓库、产品 —— 提供给 LLM 客户端（如 Claude Code、Claude Desktop 或 Cursor）使用。

• 完整。 全部 179 个已记录的 API 方法，没有一个被存根。

• 默认只读，除非你另行开启。 92 个写入方法保持不可见，除非你选择启用；关闭写入时，每个工具都会报告 readOnlyHint: true。

• 本地或远程。 面向本机客户端的 stdio，或面向互联网共享端点的、带 OAuth 2.1 (Keycloak) 的 Streamable HTTP。

"How many orders came in yesterday that aren't paid yet?"
"Which catalog products dropped below 5 in stock this week?"
"Pull the courier label for order 1234567 and tell me the tracking number."

目录

• 快速开始

• 连接客户端

• 工具

• 写入方法

• 值得了解的行为

• 远程部署（HTTP + OAuth）

• 配置参考

• 故障排除

• 开发

Related MCP server: TextQL MCP Server

快速开始

要求：Node.js 20 或更高版本，以及来自 BaseLinker 面板 账户及其他 → 我的账户 → API 下的 BaseLinker API 令牌。

git clone https://github.com/PiotrRaszkowski/baselinker-mcp.git
cd baselinker-mcp
npm install
npm run build
cp .env.example .env     # paste your token into BASELINKER_API_TOKEN

令牌也可以直接来自环境变量，其优先级高于 .env。.env 从包根目录读取，因此无论你的 MCP 客户端从哪个目录启动，服务器都能正确启动。

连接客户端

Claude Code

claude mcp add baselinker -e BASELINKER_API_TOKEN=your-token -- node /path/to/baselinker-mcp/dist/index.js

Claude Desktop、Cursor 或任何 mcpServers 配置

{
  "mcpServers": {
    "baselinker": {
      "command": "node",
      "args": ["/path/to/baselinker-mcp/dist/index.js"],
      "env": { "BASELINKER_API_TOKEN": "your-token" }
    }
  }
}

对于可从 claude.ai 访问的共享端点，请参阅 远程部署。

工具

179 个独立的工具会淹没模型的上下文及其在它们之间进行选择的能力，因此方法按照 BaseLinker 自身的分组方式进行分组：十个工具，每个对应一个 API 类别。每个工具接受一个 method 名称和一个 parameters 对象，每个工具的描述列出了它接受的方法及其参数和分页提示。

下面的计数为 read + write；写入方法仅在 BASELINKER_ALLOW_WRITES=true 时出现。

在发送任何内容之前，每个方法的参数都会根据 Zod 模式进行验证，因此格式错误的调用会返回可读的错误，而不是 BaseLinker 错误代码。未知键会被原样转发——BaseLinker 会不加警告地添加参数，而服务器不会因此中断。

写入方法

默认禁用。要启用：

BASELINKER_ALLOW_WRITES=true

禁用时，写入方法既不会出现在任何工具的 method 枚举中，也无法调用。启用会一次性打开全部 92 个——创建、更新和删除订单、产品、库存、价格、发票、发货、退货和仓库单据。其中一些会删除记录；一些会派发真实的快递发货，产生真实费用。没有按方法进行门控，因此请仅为你信任的客户端启用写入，并考虑为其他所有情况运行第二个只读实例。

值得了解的行为

速率限制。 BaseLinker 允许每分钟 100 个请求。客户端滑动窗口限制器强制执行该限制——超出的调用会排队等待，而不是失败。

分页。 列表响应有上限（订单、发票和退货通常为 100 项；目录产品为 1000 项）。每个方法的描述都带有具体提示，例如 getOrders 需要将 date_confirmed_from 设置为最后返回订单的 date_confirmed 加一秒，而 getInventoryProductsList 接受从 1 开始的 page。

文件下载。 getLabel、getProtocol、getCourierDocument、getInvoiceFile、getInventoryDocumentFile 和 getInventoryFulfillmentDeliveryLabels 将文件作为具有真实 MIME 类型的 MCP 嵌入式资源返回。传入额外的 save_to_path 参数——在本地处理，绝不会发送到 BaseLinker——可改为将文件解码到磁盘，并返回 { saved_to, extension, bytes }。这仅在 stdio 下有意义，因为服务器运行在你自己的机器上；在 HTTP 下会被拒绝并附带说明性错误。

远程部署（HTTP + OAuth）

使用 --transport http 时，服务器使用 Streamable HTTP 通信，并充当 OAuth 2.0 资源服务器（RFC 9728）：它发布受保护资源元数据，对未认证的调用返回 401 以及 WWW-Authenticate 挑战，并针对 Keycloak 领域的 JWKS 将每个访问令牌验证为 RS256 JWT。客户端从该元数据中发现领域，并通过动态客户端注册自行注册，因此任一侧都无需配置客户端 ID 或密钥。

node dist/index.js --transport http --host 0.0.0.0 --port 8000 --path /mcp

HTTP 传输在没有认证领域时拒绝启动，除非你使用 BASELINKER_MCP_AUTH_DISABLED=true 明确选择退出。这是有意为之：启用写入时，未认证的端点会把你的 BaseLinker 账户交给互联网。

deploy/ 包含完整指南——Keycloak 领域设置、带 Traefik 标签的加固 Compose 服务、Caddy 和 nginx 的反向代理片段、验证命令和威胁模型。简版如下：

docker build -t baselinker-mcp:0.2.0 .
docker run -d --name baselinker-mcp -p 8000:8000 \
  -e BASELINKER_API_TOKEN=your-token \
  -e BASELINKER_MCP_AUTH_REALM_URL=https://keycloak.example.com/realms/myrealm \
  -e BASELINKER_MCP_AUTH_BASE_URL=https://mcp.example.com \
  baselinker-mcp:0.2.0

然后将客户端指向它：

claude mcp add --transport http baselinker https://mcp.example.com/mcp

在 claude.ai 中，路径为 设置 → 连接器 → 添加自定义连接器，URL 为 https://mcp.example.com/mcp，客户端 ID 和客户端密钥留空。

在暴露它之前需要明确一点：BaseLinker 令牌是共享的。所有能登录该领域的人都操作同一个 BaseLinker 账户。其余边界请参阅 SECURITY.md。

配置参考

所有配置都是环境变量；包根目录中的 .env 会自动加载。

始终

传输

CLI 标志优先于这些变量。

OAuth —— 传输为 http 时必需

列表接受逗号或空格分隔。

故障排除

更多 OAuth 特定情况请参阅 deploy/README.md。

开发

npm run dev         # run from sources (tsx), stdio transport
npm run start:http  # built server, HTTP transport
npm test            # unit tests — fully offline, no live API calls
npm run check       # format check + typecheck + tests, what CI runs
npm run smoke       # manual smoke test against the live API (uses .env)
npm run inspect     # MCP Inspector against the built server

CONTRIBUTING.md 介绍了工具注册表的构建方式，以及在添加方法时需要注意的事项。

许可证

MIT。与 BaseLinker 无关联，也未获得其认可。