mcp-correios

@codespar/mcp-correios

Alpha release — published under the alpha npm dist-tag. Endpoint paths follow public docs and BACEN/provider conventions but have not been fully live-validated. Pin exact versions during 0.x.x-alpha. Install with npm install <pkg>@alpha.

MCP server for Correios — Brazilian postal service tracking, rates, and shipping

Quick Start

Claude Desktop

Add to ~/.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

Add to .cursor/mcp.json or .vscode/mcp.json:

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

Tools (21)

Tool	Purpose
track_package	Track a package by Correios tracking code
track_bulk	Track multiple Correios packages in a single call (up to 50 codes)
calculate_shipping	Calculate shipping rates between two CEPs
get_delivery_time	Get estimated delivery time between two CEPs
list_services	List available Correios shipping services
find_cep	Look up address by CEP via Correios
find_cep_bulk	Batch address lookup for up to 20 CEPs in a single call
list_cep_ranges	List CEP ranges (faixas de CEP) served by a given shipping service
get_delivery_modality	Get delivery modality (forma de entrega) for a CEP and service — whether delivery is domicile, agency picku...
create_prepost	Create a pre-posting order for shipping
get_prepost	Get a pre-posting order by ID
list_preposts	List pre-posting orders with optional filters (date range, status)
cancel_prepost	Cancel a pre-posting order
buy_label_range	Request a range of SIGEP tracking labels (etiquetas) for a service
post_objects	Close and post a list of pre-posted objects (fechar postagem SIGEP) — creates a PLP
list_postal_codes	Search addresses by street name or location (returns matching CEPs)
create_collection	Schedule a package collection (pickup) from an address
get_collection	Get collection request details by ID
cancel_collection	Cancel a scheduled collection request
create_reverse	Create a reverse logistics (return) order
get_reverse	Get reverse logistics order details by ID

Authentication

Correios uses Basic Auth for token generation, then Bearer token for subsequent requests. The server automatically manages authentication.

Sandbox / Testing

Correios provides a homologation environment for testing. Contact Correios for homologation credentials.

Get your credentials

1. Go to Correios CWS Portal
2. Register for API access (requires a contract with Correios)
3. Get your username and token
4. Set the environment variables

Environment Variables

Variable	Required	Description
CORREIOS_USER	Yes	Correios API username
CORREIOS_TOKEN	Yes	Correios API token

Roadmap

v0.2 (planned)

• list_postal_codes — List postal codes for a region
• get_postal_code_range — Get postal code range for a city
• create_collection — Schedule a package collection
• get_collection — Get collection request details
• create_reverse — Create a reverse logistics (return) request

v0.3 (planned)

• batch_tracking — Track multiple packages in a single request
• international_shipping — Calculate international shipping rates

Want to contribute? Open a PR or request a tool.

Links

• Correios Website
• Correios API Portal
• MCP Dev LATAM
• Landing Page

Enterprise

Need governance, budget limits, and audit trails for agent payments? CodeSpar Enterprise adds policy engine, payment routing, and compliance templates on top of these MCP servers.

License

MIT