如何通过 MCP 将 Xentral 连接到 Gemini

💡 无需安装? 直接使用 cloud.anythingmcp.com。 登录、点击 Connectors → Xentral ERP、粘贴凭证、生成 MCP API key，即可完成。无 Docker、无 git clone、无本地服务器。

Xentral + Gemini

把 Xentral ERP 连接到你的 AI：按仓库和库位查找商品与库存，查询客户和供应商、销售订单、带物流追踪的送货单、带付款状态的发票、贷项通知单、采购订单和供应商发票，并创建销售订单草稿。使用当前的 Xentral API 和 Personal Access Token。

前提条件

完整的设置说明已内置在连接器中 (在 store 中选择连接器时可见)。所需环境变量:

XENTRAL_URL, XENTRAL_TOKEN

步骤 1 — 获取凭证

1. 在 Xentral 中点击左下角的 Administration，然后进入 Account settings (Kontoeinstellungen) → Developer settings (Developer Einstellungen) → Personal Access Tokens。更快的方法：在 Smart Search 中输入 “Personal Access Token”。这一步需要管理员账户。
2. 点击 Create token（Token erzeugen），为令牌填写名称（例如 AnythingMCP-Read）、描述和有效期（默认 180 天）。
3. 为 AI 需要查看的模块授予 Read：商品和库存、客户（CRM）、销售单据（销售订单、送货单、发票、贷项通知单）、采购（采购订单、供应商、应付账款）以及付款方式和项目等设置。只有在允许 AI 准备订单草稿时，才为销售订单加上 Create 和 Delete。不要授予 Admin 权限范围。
4. 点击 Create 并立即复制令牌：Xentral 只显示一次。
5. 把 XENTRAL_URL 设为你打开 Xentral 时使用的地址，例如 https://acme.xentral.biz（或你自己的域名），不要带 /api、路径或末尾斜杠。把令牌原样填入 XENTRAL_TOKEN，不要带 Bearer 字样，然后安装连接器。
6. 先运行 xentral_list_products：如果返回了商品，说明 URL 和令牌都没问题。

令牌有效期和权限：令牌会在你选择的日期失效，180 天未使用的令牌会被 Xentral 删除。令牌的权限之后无法修改：如需更改，请创建新令牌并替换 XENTRAL_TOKEN。AI 只能看到令牌有权读取的模块。

使用 id，而不是打印的编号：每个工具都使用 Xentral 的内部 id，而不是单据上打印的商品编号、单据编号或客户编号。AI 会先用列表类工具找到 id，可以按 number、documentNumber 或 customerNumber 筛选，也可以用 search。客户的 id 同时也是其地址 id：单据中显示为 address.id，xentral_create_sales_order 中以 addressId 传入。客户筛选只支持精确匹配，因此要按名称的一部分查找客户时，AI 会用 xentral_list_invoices 或 xentral_list_sales_orders 搜索该客户的单据，再从中取得 address.id。

筛选：列表类工具接受一组必须全部满足的条件，每个条件包含字段（key）、运算符（op）和值（value）。例如未付发票：[{"key": "paymentStatus", "op": "in", "value": ["pending", "partiallyPaid"]}]。运算符包括 equals, in, contains, startsWith, greaterThanOrEquals 和 lessThan 等；每个工具都会列出它接受的字段。单据日期格式为 YYYY-MM-DD。

搜索和排序单据：对于销售订单、送货单、发票、贷项通知单和采购订单，search 会搜索单据编号、客户或供应商的名称和编号、邮箱、邮编以及外部订单号。sort 接受字段名，前面加减号表示降序（-documentDate），include 可嵌入 lineItems（明细行）或 address 等关联数据。

状态：销售订单的状态为 draft、released、completed 或 cancelled；发票、送货单和采购订单还可能是 sent。发票和贷项通知单的付款状态（paymentStatus）为 pending, paid, partiallyPaid, cancelled, partiallyCancelled, badDebt 或 debited。

库存：xentral_get_product_stock 返回总计以及按仓库、按销售渠道的相同数据。sellable 是还能向客户承诺的数量，physical 是货架上的实际数量，reserved 是被未完成订单占用的数量。仓库（Lager）下设库位（Lagerplätze）：xentral_list_product_storage_locations 显示某个商品放在哪里，xentral_list_storage_location_items 显示某个库位上有什么。

发货和付款：xentral_list_delivery_note_shipments 返回送货单的承运商、追踪号和追踪链接。xentral_get_invoice_balance 显示某张发票已入账的付款以及仍未付的金额。

分页：单据列表使用 page 和 perPage（最多 1000，默认 25）；其他列表使用 page 和 pageSize（10 到 50）。

写入：xentral_create_sales_order 只会为现有客户创建草稿：没有订单号，在有人于 Xentral 中检查并发布之前，不会预留或发出任何货物。AI 未指定价格时，Xentral 会使用该客户和商品的价格。xentral_delete_sales_order_draft 用于删除此类草稿，安装时默认关闭；已发布、已完成或已取消的订单 Xentral 不允许删除。其他所有工具都只读。

只读设置：只给令牌 Read 权限，并在连接器页面关闭 xentral_create_sales_order。

速率限制：无论哪种方案，Xentral 每个实例每分钟大约允许 100 个请求；超出后返回 429 并附带 Retry-After 头。一次带筛选的列表调用胜过多次单独查询。

常见错误：401 表示令牌错误、已过期或已被删除。403 表示令牌缺少该模块的权限：请创建一个带有该权限的新令牌。400 “Generic request validation failed” 或 “filter must be an array” 表示使用了工具不接受的筛选字段或运算符，或者值的格式有误。404 “Route not found” 表示 XENTRAL_URL 中包含 /api/v1 之类的路径，或该实例尚未提供这个接口。删除销售订单时返回 409，表示它已经不是草稿。

步骤 2 — 安装 adapter

curl -fsSL https://raw.githubusercontent.com/HelpCode-ai/anythingmcp/main/docker-compose.quickstart.yml -o docker-compose.yml
printf 'JWT_SECRET=%s\nENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
docker compose up -d

步骤 3 — 在 Gemini 中添加连接器

你的服务器 URL： 在 AnythingMCP 中打开 MCP Servers → 此连接器所在的服务器，复制它的 URL（https://cloud.anythingmcp.com/mcp/…）。本指南中出现 YOUR_SERVER_ID 的地方都用它替换。

Gemini CLI 从 ~/.gemini/settings.json（Windows 上为 %USERPROFILE%\.gemini\settings.json）读取 MCP 服务器。添加：

{
  "mcpServers": {
    "anythingmcp": {
      "httpUrl": "https://cloud.anythingmcp.com/mcp/YOUR_SERVER_ID",
      "headers": { "X-API-Key": "YOUR_MCP_API_KEY" }
    }
  }
}

1. 在 AnythingMCP 的 MCP Servers → 你的服务器 → API keys 中创建 MCP API 密钥，并用它替换 YOUR_MCP_API_KEY。
2. 保存文件并重启 gemini。
3. 在 Gemini CLI 中运行 /mcp（或在终端运行 gemini mcp list），anythingmcp 应显示为已连接。
4. 开始输入提示，Gemini CLI 现在可以调用 Xentral 的工具。

可用工具

示例提示

• “商品 700123 在每个仓库还能卖多少件？它放在哪些库位上？”
• “哪些发票还没付款或只付了一部分？列出客户、金额和催款级别，最早的排在前面。”
• “订单 200345 的包裹现在在哪里？告诉我承运商和追踪链接。”
• “为客户 10001 创建一个销售订单草稿：商品 700123 共 20 件，商品 700456 共 5 件，期望交货日期 10 月 20 日。”

FAQ

Gemini CLI 从哪里读取 MCP 服务器？ 用户级配置位于 ~/.gemini/settings.json，项目级配置位于项目内的 .gemini/settings.json。gemini mcp list 会列出每个服务器及其连接状态。

下一步

• 连接器主页
• 连接到 Claude
• 连接到 ChatGPT