shippo-mcp

Name: shippo-mcp
Author: Shippo

远程服务

goshippo.com金融数据314 周前更新

文档代码仓库访问官网

关于 shippo-mcp

Shippo 的 AI 集成仓库为助手提供运输工作流技能，涵盖地址校验、运费比较、标签购买、包裹追踪和批量处理，并配置 Shippo 托管的 OAuth MCP 服务以执行运输操作。

主要功能

01校验地址
02比较多家承运商费率
03购买含报关信息的标签
04追踪包裹及状态历史
05处理 CSV 批量货件
06分析运输成本

适用场景

01检查并规范货件地址
02发货前比较承运商费率
03购买国内和国际货件标签
04追踪包裹或批量处理 CSV

MCP 相关

Shippo 在 https://mcp.shippo.com 托管远程 MCP 服务，通过 Streamable HTTP 和每用户 Shippo OAuth 接入。Codex 与 Claude Code 插件连接该服务以执行运输操作。

#shipping #logistics #carriers #usps #ups #fedex #dhl #tracking #address-validation #ecommerce #dpd #tracking-packages

配置

远程服务无需本地安装。选择你使用的客户端，复制配置或使用一键安装。

服务地址https://mcp.shippo.com

一键复制安装命令

Claude CodeTerminalclaude mcp add --transport http shippo https://mcp.shippo.com

Cursor.cursor/mcp.json{"mcpServers":{"shippo":{"type":"http","url":"https://mcp.shippo.com"}}}在 Cursor 中打开

VS Code.vscode/mcp.json{"servers":{"shippo":{"type":"http","url":"https://mcp.shippo.com"}}}在 VS Code 中打开

Claude Desktopclaude_desktop_config.json{"mcpServers":{"shippo":{"type":"http","url":"https://mcp.shippo.com"}}}

Windsurf~/.codeium/windsurf/mcp_config.json{"mcpServers":{"shippo":{"serverUrl":"https://mcp.shippo.com"}}}

命令在终端中运行；JSON 粘贴到对应客户端的 MCP 配置后重启。需要授权的服务会在首次连接时提示登录。

工具

详细介绍

Shippo AI

本仓库是一站式平台，可用于构建由 AI 驱动的 Shippo 运输集成。

其中包含：

9 个 Agent Skills：为 AI 助手提供工作流知识，涵盖运费比价、地址验证、购买面单（含海关）、包裹追踪、批量发货、运输成本分析、起草支持工单、集成最佳实践以及 SDK/API 升级。只需编写一次，即可分发到多个 AI 平台。
Claude Code 插件（providers/claude/plugin/）：通过 --plugin-dir 或插件市场安装（/plugin marketplace add goshippo/ai）。
OpenAI Codex 插件（providers/codex/plugin/）：通过 Codex 插件市场安装；内含各项技能和 OAuth MCP 服务。
ClawHub 技能（providers/clawhub/skills/shippo/）：通过 openclaw skills install @shippo/shippo 安装。
Claude 应用（claude.ai / Desktop / Cowork）：整个插件打包为一个可直接上传的 ZIP（shippo-plugin.zip），并附加到每个 GitHub Release。上传一次即可安装全部技能。
知识包（ChatGPT 和其他聊天助手）（providers/knowledge-pack/shippo-knowledge-pack.md）：为不加载 SKILL.md 文件夹的助手提供一个整合后的 Markdown 文件。用户可将其添加到聊天、Custom GPT 的知识库或 Project 中作为上下文。它提供运输相关知识；实时操作仍通过托管的 MCP 连接器完成。

什么是技能？

技能是一个包含 SKILL.md 文件的文件夹，其中有 YAML frontmatter（至少包含 name 和 description）以及 Markdown 指令，用于告诉 AI 助手如何执行特定任务。技能还可以捆绑参考文档、脚本和模板。

rate-shopping/
├── SKILL.md           # required: metadata + instructions
└── README.md          # optional: human-facing orientation

Agent 会分三个阶段通过渐进式披露加载技能：

发现：启动时，Agent 只加载每项技能的 name 和 description，以便判断技能何时可能适用。
激活：当用户提示词与技能描述匹配时，Agent 会将完整的 SKILL.md 正文加载到上下文中。
执行：Agent 按照指令操作，并可在过程中加载引用的文件（shippo/references/*.md）。

Agent Skills 是由 Anthropic 最初开发的开放标准。同一个 SKILL.md 可用于 Claude Code、Cursor、OpenAI Codex、GitHub Copilot、VS Code 以及 30 多种其他 Agent。

在本仓库中，skills/ 下的 9 项技能是规范来源。同步脚本会自动将其传播到 providers/claude/plugin/skills/ 和 providers/codex/plugin/skills/（一对一镜像）、providers/clawhub/skills/shippo/（整合摘要）以及 providers/knowledge-pack/shippo-knowledge-pack.md（为 ChatGPT 和其他不加载技能的助手准备的单个可直接上传的知识包）。

Model Context Protocol（MCP）

Shippo 托管了一个支持按用户进行 OAuth 身份验证的远程 MCP 服务。每位用户只需通过 Shippo 授权一次，无需复制 API 密钥。Claude Code 和 OpenAI Codex 插件会连接到此端点，并在首次使用时触发登录。

URL	传输方式	身份验证
`https://mcp.shippo.com`	Streamable HTTP	按用户进行 Shippo OAuth

有关各工具的语义和用法，请参阅 Shippo MCP 服务文档。

正在使用 OpenAI 构建？请参阅通过 OpenAI Responses API / Agents SDK 使用 Shippo MCP，了解开发者配置（无需提交申请）。

功能

此仓库中的 9 个技能按参与模式组织：依据用户正在做什么，而不是产品界面。AI 助手会先将用户意图匹配到三种模式之一，再加载相应技能。

决策，“我该从哪里开始？”

技能	功能
`shippo-best-practices`	Shippo 集成决策路由器，涵盖应使用哪个 API、测试模式与实时模式的规范、响应处理和关键规则

执行，“运行此工作流”

技能	功能
`address-validation`	验证、解析并标准化美国和国际地址
`rate-shopping`	比较 USPS、UPS、FedEx、DHL 和 30 多家承运商的运费
`label-purchase`	购买国内和国际运输标签，并处理海关事宜
`tracking`	跟踪各承运商的包裹，查看状态历史记录、子状态代码和 Webhook
`batch-shipping`	处理货件 CSV 文件并批量生成标签
`shipping-analysis`	分析成本、优化包裹尺寸、比较承运商并审查历史支出
`shippo-support-ticket`	为单个货件或标签生成自动分类、带路由标签的支持工单（人工可读版 + JSON）；只读，供 Shippo 支持人员使用

维护，“升级或迁移”

技能	功能
`upgrade-shippo`	指导升级 SDK 版本、更新 MCP 服务并迁移不兼容变更

已经知道所需工作流的用户（“购买标签”“跟踪此包裹”）会直接使用“执行”技能。刚开始的用户（“我正在构建带有运输功能的结账流程，该从哪里开始？”）会使用“决策”技能，该技能会将他们引导至合适的“执行”技能。维护也有专属技能，因此生产就绪性问题不会与工作流内容混在一起。

这 9 个技能依赖 skills/shippo/references/ 下的 11 份共享参考文档（承运商、海关、CSV 格式、错误参考等）。技能会按需加载参考文档；AI 不会将全部 11 份文档都载入上下文，而只会加载给定工作流所需的文档。

安装

Claude Code

git clone https://github.com/goshippo/ai.git
claude --plugin-dir ./ai/providers/claude/plugin

也可以从插件市场安装：

/plugin marketplace add goshippo/ai
/plugin install shippo@shippo

首次使用时，运行 /mcp，选择 Shippo 服务，然后登录以通过 OAuth 授权 MCP（无需复制 API 密钥）。

技能以 /shippo: 为命名空间：可直接通过 /shippo:rate-shopping、/shippo:label-purchase、/shippo:tracking 等命令调用，也可以用自然语言描述你正在做什么。

OpenAI Codex

Codex 会从此仓库的插件市场安装 Shippo 插件（技能 + OAuth MCP）：

codex plugin marketplace add goshippo/ai
codex plugin add shippo@shippo   # install the "shippo" plugin
codex mcp login shippo           # authorize the remote MCP over OAuth

详情请参阅 providers/codex/plugin/。（如果只想获取技能内容而不安装插件，Codex 的 skill-installer 也可以安装单个 providers/codex/plugin/skills/<name> 目录。）

ClawHub

openclaw skills install @shippo/shippo

（在 ClawHub 注册表上以 @shippo/shippo 发布。）

Claude 应用（claude.ai / Desktop / Cowork）

Claude 应用会将插件作为一个 ZIP 文件加载。shippo-plugin.zip（包含整个插件：清单、OAuth MCP 配置和所有技能）会附加到每个 GitHub Release 中。下载后，通过应用的插件 UI 添加。Team/Enterprise 管理员可以一步完成组织范围的配置：Organization settings → Plugins → 上传 shippo-plugin.zip → 设置 "Installed by default"（或分配给某个群组），即可让所有成员使用这些技能。（必须在 Organization settings 中启用代码执行。）

在本地构建 ZIP：npm run build:app-plugin（输出位于 dist/app-plugin/）。

Shippo 账户

你需要一个 Shippo 账户。获取运费和验证地址均不收费；购买标签时会使用 Shippo 的承运商折扣运费，并从你的账户扣费。Claude Code 和 Codex 插件会在首次使用时通过 OAuth 为每位用户单独授权，因此无需复制 API 密钥。

工作原理

此插件包含两部分，二者之间有明确的分工：

技能（本仓库）：跨工具的工作流说明：路由决策（结账 vs 单个标签 vs 批量处理）、用户体验关卡（“购买实时模式标签前先询问”）、CSV 导入、验证顺序、测试/实时模式规范、响应处理规则。用户请求符合某项技能的描述时，该技能会在激活时加载。
MCP 服务（文档：每个工具的语义：工具名称、参数、返回形式、单次调用限制。每项工具的描述都很简洁，只包含一个动词短语和一个工具。这里刻意不重复工作流指南。

技能教会助手如何通过多次 API 调用完成发货。MCP 服务则为助手提供每个工具在单次调用中的准确信息。两者的内容按设计相互独立，沿用了 Stripe 的先例（简洁的 mcp.stripe.com 工具描述、丰富的 stripe/agents 技能）：因此，原生 MCP 用户能获得准确的单工具语义，安装技能的用户还能获得工作流说明，且两者不会相互矛盾。

仓库结构

skills/：规范的技能内容（9 项技能 + 11 份共享参考资料）。在此处编辑；其他内容都由此生成。
providers/claude/plugin/：Claude Code 插件分发内容。通过 scripts/sync.js 与规范内容保持 1:1 镜像。
providers/codex/plugin/：OpenAI Codex 插件。skills/ 通过 scripts/sync.js 与规范内容保持 1:1 镜像；手动编写的 .codex-plugin/plugin.json + .mcp.json 则包含清单和 OAuth MCP 接线配置。此插件登记在仓库根目录的 .agents/plugins/marketplace.json 中。
providers/clawhub/skills/shippo/：ClawHub 捆绑包分发内容。SKILL.md 由 SKILL.md.template（手工整理的引导内容）和规范技能正文通过 scripts/compose-clawhub-digest.js 自动生成。参考资料通过 scripts/build-clawhub-bundle.js 自动同步。
dist/app-plugin/：供 Claude 应用使用的单个 shippo-plugin.zip，由 scripts/build-app-plugin.js 从 providers/claude/plugin/ 构建而来（不提交到仓库；按需构建，也会在发布时构建）。
scripts/：同步、合成和构建辅助脚本。

编写内容

# 1. Edit canonical content
vim skills/<skill-name>/SKILL.md
# (or skills/shippo/references/<name>.md, or providers/clawhub/skills/shippo/SKILL.md.template
#  if you're changing ClawHub-only framing)

# 2. Sync + verify (one command)
npm test

# 3. Commit canonical edits AND synced output together
git add -A && git commit -m "..."

npm test 会运行所有同步步骤（Claude Code + Codex 镜像、ClawHub 摘要合成、ClawHub 参考资料同步），并验证结果是否内部一致。CI 运行相同的命令。无需运行 npm install；仓库没有第三方依赖，只有脚本。

预览修改

**Claude Code：**在仓库根目录运行 claude --plugin-dir ./providers/claude/plugin，即可启动已加载本地插件的 Claude Code。对 skills/<name>/SKILL.md 的修改会立即生效。技能以 /shippo: 为命名空间（例如 /shippo:rate-shopping）。
**ClawHub 摘要：**运行 npm test 后，渲染结果位于 providers/clawhub/skills/shippo/SKILL.md：直接阅读即可查看 ClawHub 用户安装后会看到的内容。目前还没有本地服务预览方式。

完整的编写规范请参阅 CONTRIBUTING.md，其中包括版本更新规则和技能内容中的交叉引用措辞规则。