mcp-correios

@codespar/mcp-correios

アルファ版 — alpha npm 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	1 回の呼び出しで複数の Correios 荷物を追跡します（最大 50 件）
calculate_shipping	2 つの CEP 間の送料を計算します
get_delivery_time	2 つの CEP 間のお届け予定日数を取得します
list_services	利用可能な Correios の配送サービスを一覧表示します
find_cep	Correios を通じて CEP から住所を検索します
find_cep_bulk	1 回の呼び出しで最大 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 — 1 回のリクエストで複数の荷物を追跡します
• international_shipping — 国際配送の送料を計算します

コントリビュートをご希望ですか？PR を作成するか、ツールをリクエストしてください。

リンク

• Correios のウェブサイト
• Correios API ポータル
• MCP Dev LATAM
• ランディングページ

エンタープライズ

エージェントの決済にガバナンス、予算上限、監査証跡が必要ですか？CodeSpar Enterprise は、これらの MCP サーバーにポリシーエンジン、決済ルーティング、コンプライアンステンプレートを追加します。

ライセンス

MIT