mcp-correios

@codespar/mcp-correios

Alpha 版 — 通过 npm 的 alpha dist-tag 发布。端点路径遵循公开文档和 BACEN／服务提供商的惯例，但尚未经过全面的线上验证。在 0.x.x-alpha 阶段，请固定使用确切版本。使用 npm install <pkg>@alpha 安装。

用于 Correios 的 MCP 服务 — 巴西邮政服务的包裹追踪、费率查询和寄件服务

快速开始

Claude Desktop

添加到 ~/.config/claude/claude_desktop_config.json：

{
  "mcpServers": {
    "correios": {
      "command": "npx",
      "args": ["-y", "@codespar/mcp-correios"],
      "env": {
        "CORREIOS_USER": "your-user",
        "CORREIOS_TOKEN": "your-token"
      }
    }
  }
}

Claude Code

claude mcp add correios -- npx @codespar/mcp-correios

Cursor / VS Code

添加到 .cursor/mcp.json 或 .vscode/mcp.json：

{
  "servers": {
    "correios": {
      "command": "npx",
      "args": ["-y", "@codespar/mcp-correios"],
      "env": {
        "CORREIOS_USER": "your-user",
        "CORREIOS_TOKEN": "your-token"
      }
    }
  }
}

工具（21 个）

工具	用途
track_package	根据 Correios 追踪码追踪包裹
track_bulk	在一次调用中追踪多个 Correios 包裹（最多 50 个追踪码）
calculate_shipping	计算两个 CEP 之间的运费
get_delivery_time	获取两个 CEP 之间的预计配送时间
list_services	列出可用的 Correios 配送服务
find_cep	通过 Correios 根据 CEP 查询地址
find_cep_bulk	在一次调用中批量查询最多 20 个 CEP 的地址
list_cep_ranges	列出指定配送服务覆盖的 CEP 范围（faixas de CEP）
get_delivery_modality	获取 CEP 和服务对应的配送方式（forma de entrega）——配送方式是送货上门、网点自取……
create_prepost	创建寄件预登记订单
get_prepost	根据 ID 获取寄件预登记订单
list_preposts	列出寄件预登记订单，可选按日期范围和状态筛选
cancel_prepost	取消寄件预登记订单
buy_label_range	申请一段服务对应的 SIGEP 追踪标签（etiquetas）
post_objects	关闭并寄送一批已预登记的物品（fechar postagem SIGEP）——创建 PLP
list_postal_codes	按街道名称或地点搜索地址（返回匹配的 CEP）
create_collection	安排从某地址上门收取包裹
get_collection	根据 ID 获取收件请求详情
cancel_collection	取消已安排的收件请求
create_reverse	创建逆向物流（退货）订单
get_reverse	根据 ID 获取逆向物流订单详情

身份验证

Correios 使用 Basic Auth 生成令牌，后续请求则使用 Bearer 令牌。服务会自动管理身份验证。

沙盒／测试

Correios 提供用于测试的认证环境。请联系 Correios 获取认证环境凭据。

获取凭据

1. 前往 Correios CWS Portal
2. 注册 API 访问权限（需要与 Correios 签订合同）
3. 获取用户名和令牌
4. 设置环境变量

环境变量

变量	必填	说明
CORREIOS_USER	是	Correios API 用户名
CORREIOS_TOKEN	是	Correios API 令牌

路线图

v0.2（计划中）

• list_postal_codes — 列出某个地区的邮政编码
• get_postal_code_range — 获取某个城市的邮政编码范围
• create_collection — 安排上门收取包裹
• get_collection — 获取收件请求详情
• create_reverse — 创建逆向物流（退货）请求

v0.3（计划中）

• batch_tracking — 在单个请求中追踪多个包裹
• international_shipping — 计算国际运费

想要参与贡献？提交 PR 或申请工具。

链接

• Correios 网站
• Correios API 门户
• MCP Dev LATAM
• 落地页

企业版

需要为 Agent 付款提供治理、预算限制和审计记录？CodeSpar Enterprise 在这些 MCP 服务之上增加了策略引擎、付款路由和合规模板。

许可证

MIT