mcp-correios — Claude Code MCP server: features and setup
Connects your coding agent to the Correios postal API in Brazil. Tracks packages, calculates shipping rates, and searches addresses by CEP postal code.
claude mcp add mcp-correios -e CORREIOS_TOKEN=<CORREIOS_TOKEN> -- npx -y @codespar/mcp-correiosWhat mcp-correios does
This server exposes 21 tools designed for Brazilian postal logistics. Agents can check package tracking status individually or in batches of up to 50 codes. It also quotes shipping prices between two postal codes, calculates transit times, and resolves street addresses for up to 20 CEPs in one request.
Beyond basic lookups, the package handles core shipping operations. It can create pre-posting entries, request SIGEP label intervals, generate dispatch PLPs, schedule courier pickups, and trigger return orders. Authentication runs under the hood: the server exchanges basic credentials for session tokens without manual intervention.
Calls will fail immediately without an active Correios corporate agreement. You must obtain API credentials from the CWS portal and pass them through CORREIOS_USER and CORREIOS_TOKEN. Because the package is currently an alpha release, locking exact package versions prevents unexpected breaking changes.
What it helps with
- track packages across Brazil using official Correios codes
- calculate shipping costs and transit times between two CEP codes
- resolve street names and municipal data from Brazilian postal codes
- generate SIGEP pre-posting slips and finalize dispatch batches
- schedule warehouse pickups and reverse logistics return requests
Example prompts for the agent
- Track package
AA123456789BRthrough Correios and report its latest status - Calculate delivery rates and estimated transit days from CEP
01001-000to20040-002 - Look up the address details for CEP
70040-010
How to install mcp-correios
Platform CLI
claude mcp add mcp-correios -e CORREIOS_TOKEN=<CORREIOS_TOKEN> -- npx -y @codespar/mcp-correiosReplace <…> with your own values
Platform CLI
codex mcp add correios --env CORREIOS_TOKEN=<CORREIOS_TOKEN> -- npx -y @codespar/mcp-correiosReplace <…> with your own values
Config file
{
"mcpServers": {
"correios": {
"command": "npx",
"args": [
"-y",
"@codespar/mcp-correios"
],
"env": {
"CORREIOS_TOKEN": "<CORREIOS_TOKEN>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"correios": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@codespar/mcp-correios"
],
"env": {
"CORREIOS_TOKEN": "<CORREIOS_TOKEN>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e CORREIOS_TOKEN=<CORREIOS_TOKEN> correios npx -y @codespar/mcp-correiosReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about mcp-correios
How to install mcp-correios in Claude Code?
Run claude mcp add mcp-correios -e CORREIOS_TOKEN=<CORREIOS_TOKEN> -- npx -y @codespar/mcp-correios in your terminal. Replace the placeholder with your actual API token.
What does mcp-correios do?
It equips your AI assistant with Brazilian postal operations. It handles parcel tracking, rate calculation, CEP lookups, and shipping order preparation directly through Correios systems.
What prerequisites are required to use mcp-correios?
You need a registered business contract with Correios and credentials from their CWS portal. The server requires both CORREIOS_USER and CORREIOS_TOKEN environment variables to access the endpoints.
