如何通过 MCP 将 YunExpress 连接到 Gemini

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

YunExpress + Gemini

云途物流（YunExpress）OMS API：目的国家、运输方式和货物类型，运费试算，带跟踪号的运单，面单，尾程承运商，轨迹事件和实际扣费，修改重量和拦截。删除运单在安装时默认关闭。

前提条件

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

YUNEXPRESS_API_TOKEN

步骤 1 — 获取凭证

设置大约需要 5 分钟。你需要一个开通了 API 的云途物流客户账号。

1. 登录云途物流客户中心（www.yunexpress.cn 或你的云途客户门户），打开 API 栏目。记下你的客户编号（例如 C12345）和 API 密钥；如果还没有密钥，就在那里申请。
2. 云途使用 Authorization: Basic <token> 认证，token 是"客户编号 + & + API 密钥"的 Base64（中间是 &，不是冒号）。在你的电脑上计算一次，例如 printf '%s' 'C12345&YourApiSecret' | base64，只把结果粘贴到 YUNEXPRESS_API_TOKEN。它会加密保存。
3. 安装连接器并运行 yunexpress_list_countries：它会列出目的国家，并确认 token 可用。

使用哪个 API：连接器使用云途的 OMS API（1.4.x 版本），地址为 http://oms.api.yunexpress.com。这个主机只支持普通 HTTP。云途还有一个较新的开放平台（openapi.yunexpress.cn），每个请求都要用时间戳和 OAuth token 签名；本连接器不使用它。

可读取的内容：目的国家及其两位代码；你账号下的运输方式（物流产品），包括代码、中英文名称和是否带轨迹，也可以只看服务某个国家的方式；货物类型，例如普货或带电货物；按运输方式的运费试算，包括基础运费、挂号费、燃油费和其他费用、总价、币种、计费重量和时效（yunexpress_get_price_quote，可传邮编以计算偏远附加费）；运单信息，包括运单号、客户订单号、跟踪号、运输方式、状态、重量、收件人、申报明细和费用；运单的发件人地址；轨迹，包括包裹状态、轨迹状态、尾程承运商、签收证明和事件（yunexpress_get_tracking 按你的轨迹显示设置返回，yunexpress_get_full_tracking 在运输方式支持时返回完整轨迹）；尾程承运商及其单号；云途称重并结算后实际扣除的费用。

发一个包裹：AI 先按国家和货物类型查可用的运输方式并试算运费，然后调用 yunexpress_create_orders，每次 1 到 10 票。每票结果包含 Success、WayBillNumber、TrackingNumber 和 TrackType（1 有跟踪号，2 待分配，3 无跟踪号）。跟踪号待分配时，之后用 yunexpress_get_tracking_numbers 按客户订单号获取（结果缓存 30 分钟）。yunexpress_get_labels 以临时 PDF 链接返回最多 50 票的面单。

可写入的内容：yunexpress_create_orders 会创建真实运单，yunexpress_update_weight 在云途称重前修改预报重量，yunexpress_intercept_order 附上原因请求云途拦截包裹。每次写入前，AI 会先向你展示运单（收件人、运输方式、重量、报关信息），等你同意。如果超时且结果不明，它会先用 yunexpress_get_order 查询运单再重试，避免重复下单。

安装时关闭：yunexpress_delete_order，它会删除云途尚未收货的运单，且无法撤销。团队需要时由管理员开启。

数值和单位：重量单位为 kg（最多 3 位小数），尺寸为整数 cm，申报价值（UnitPrice）为单件价值，币种由 CurrencyCode 指定。OrderNumber 可以填运单号、客户订单号或跟踪号；拦截和删除时用 OrderType 说明是哪种（1 运单号，2 客户订单号，3 跟踪号）。包裹状态：0 未知，1 已提交，2 运输中，3 已签收，4 已收货，5 已取消，6 投递失败，7 已退回。轨迹状态：0 查询不到，10 预报，20 运输中，30 到达待取，40 投递失败，50 已签收，60 异常，80 未知，90 已退回，100 已取消。

限制：没有分页，列表一次返回。创建运单每次最多 10 票，面单每次最多 50 票。云途返回代码 10000 表示达到请求上限，请稍等再试。

常见错误：每个响应都有 Code（0000 表示成功）、Message、位于 Item 或 Items 中的数据，以及可提供给云途客服的 RequestId。HTTP 421 且 ResultCode 为 401，或代码 1002、1003，表示 token 错误：请用客户编号和密钥以 & 连接后重新计算。1004 参数错误，1006 无数据，1011 部分成功，2004 客户订单号重复，2005 运单已存在，2006 该运输方式没有跟踪号，2009 重量必须大于 0，2010 该运输方式不服务目的地，9999 平台错误。

本连接器不使用云途开放平台，也不管理你的账号、账单或付款：它读取的费用数据只有运费试算和每票运单的实际扣费。

步骤 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 现在可以调用 YunExpress 的工具。

可用工具

示例提示

• “哪些云途运输方式可以发德国？其中哪些带轨迹？”
• “帮我试算一个带电、0.35 kg、20 x 15 x 5 cm 的包裹发往法国，按运输方式列出总价和时效。”
• “用运输方式 THPHR 为 SO-1042 创建一票发往柏林 Anna Muster 的云途运单。先给我看收件人、重量和申报明细。”
• “跟踪号 YT2430012345678901 的包裹现在在哪里？尾程由哪家承运商派送？”
• “把今天 SO-1040 到 SO-1045 这几票的面单合成一个 PDF 给我。”

FAQ

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

下一步

• 连接器主页
• 连接到 Claude
• 连接到 ChatGPT
• 连接到 Cursor
• 连接到 Meta Muse
• 连接到 Microsoft Copilot