# Correios MCP

> Correios (Brazil) MCP gives your AI agent full control over Brazilian logistics. You can instantly track packages, get precise shipping costs and delivery deadlines for services like PAC or SEDEX, and validate addresses using any Brazilian CEP code. Stop guessing rates; automate everything from tracking updates to calculating postage fees directly through natural conversation.

## Overview
- **Category:** industry-titans
- **Price:** Free
- **Tags:** correios, brazilian-post, object-tracking, shipping-calculation, cep-search, sedex-pac, logistics-api

## Description

Running e-commerce in Brazil means dealing with complex postal rules. This MCP connects your AI agent straight into Correios, the national carrier. You can use it to track packages and find out exactly where an item is at any point in time. It calculates shipping prices and estimates delivery times for specific routes, whether you're sending a small box or a large shipment. Plus, if you have a Brazilian zip code (CEP), this MCP validates the whole address—street, neighborhood, city—so your shipments never get returned due to bad data. Vinkius makes connecting this critical infrastructure simple; your agent just asks for the info it needs.

## Tools

### calculate_price_deadline
Calculates the total cost and expected delivery window for shipping between two points.

### get_contract_status
Checks if your business contract with Correios is active or requires attention.

### get_unit_info
Retrieves specific details about a local post office unit by its identifier.

### list_contract_services
Shows all the specific postage services your account is authorized to use.

### list_unit_types
Lists every type of postal unit available within the Correios network.

### lookup_cep
Uses a Brazilian zip code (CEP) to retrieve the full official address details, including street and neighborhood.

### search_units_by_cep
Searches for nearby post office locations based on a provided CEP area.

### track_object
Inputs a tracking code and returns the current location and status history of that specific package.

## Prompt Examples

**Prompt:** 
```
Track Correios object 'QI123456789BR' and show its latest status.
```

**Response:** 
```
Connecting to Correios tracking service... Object 'QI123456789BR' was 'Delivered' (Objeto entregue ao destinatário) today at 2:30 PM in São Paulo, SP. Would you like me to see the full movement history?
```

**Prompt:** 
```
Calculate shipping for a 2kg box from CEP 01310-100 to 20040-002.
```

**Response:** 
```
Querying Correios price and deadline engine... For a 2kg package from SP to RJ: 1. SEDEX (R$ 35.50, 1 business day), 2. PAC (R$ 22.10, 5 business days). Which service would you like to choose?
```

**Prompt:** 
```
Find the address details for CEP '01310-914'.
```

**Response:** 
```
Searching Brazilian zip codes... CEP 01310-914 corresponds to: Avenida Paulista, 1159, Bela Vista, São Paulo - SP. This is a business district zone.
```

## Capabilities

### Track a Shipment Status
Enter a tracking code and receive real-time, granular updates on a package's journey.

### Calculate Shipping Costs and Deadlines
Provide two zip codes and the package weight to get multiple service options (like PAC or SEDEX) with associated prices and expected delivery dates.

### Validate a Brazilian Address
Input a CEP code, and the MCP returns the complete official street name, neighborhood, and city details.

### Find Local Post Office Units
Search for nearby post office branches or operational units using only a given CEP code.

### Manage Contract Details
Check the status of your account, list available services, and retrieve specific unit information required for billing.

## Use Cases

### Handling a Shipment Quote for a New Client
A client needs shipping rates from São Paulo (CEP 01310-100) to Salvador (CEP 40010-000). Instead of calling the sales team, your agent uses `calculate_price_deadline` and instantly returns a table showing both SEDEX and PAC options with clear price points.

### Fixing an Incorrectly Entered Shipping Address
The warehouse worker only has 'CEP 01310-914'. They use `lookup_cep` to verify the full address (Avenida Paulista, 1159) before printing the label, avoiding a costly return trip.

### Checking Contractual Service Availability
The operations lead needs to confirm if their current contract supports express international services. They run `list_contract_services` and immediately see if 'SEDEX' is listed, preventing a service failure later.

### Investigating a Delayed Package
A customer calls about package 'QI123456789BR'. The agent uses `track_object` and immediately pulls up the full history showing exactly where it was last scanned, giving the client an immediate answer.

## Benefits

- Stop manually checking tracking sites. Use `track_object` to get the full movement history of any package using just its code.
- Save money and time on quotes. The `calculate_price_deadline` tool gives you multiple service options (like PAC vs SEDEX) with clear costs and estimated delivery dates in one query.
- Never accept a bad address again. Running `lookup_cep` validates the full street, neighborhood, and city details from just the CEP code.
- Speed up your setup process. You can use `list_contract_services` to see exactly which postage services are available under your account without calling multiple internal systems.
- Improve local mapping accuracy. If you need to find a post office near an address, run `search_units_by_cep` instead of guessing the closest branch.

## How It Works

The bottom line is you talk to your agent like talking to a human logistics expert; it handles all the complex Brazilian postal rules for you.

1. First, you connect your AI agent to this MCP by providing your necessary contract credentials (Username, Password, Contract Number) through the Vinkius catalog.
2. Next, you simply ask your agent a question—for example, 'What's the cost of shipping from São Paulo to Rio de Janeiro?'
3. The MCP runs the query, interacts with Correios systems, and returns a formatted answer containing multiple service options, prices, and deadlines.

## Frequently Asked Questions

**How do I use the calculate_price_deadline tool?**
You provide two zip codes (CEP) and the package weight. The MCP returns multiple options, detailing costs and estimated delivery days for services like PAC or SEDEX.

**Does lookup_cep verify a street address?**
Yes. It doesn't just give you the neighborhood; it retrieves the complete official street name, number, city, and state associated with that CEP code.

**What is the difference between search_units_by_cep and get_unit_info?**
`search_units_by_cep` finds nearby post office locations based on an area. `get_unit_info` requires a specific unit ID to pull detailed information about that single branch.

**Can I check my account status with get_contract_status?**
Yes, this tool checks the current operational standing of your Correios contract. This is essential before running any large-scale shipment operation to prevent failures.

**Before running `track_object`, what credentials must I provide for authentication?**
You need to pass your Username, Password, and Contract Number obtained from the official Correios Web Services Portal. The MCP uses these keys to authenticate your request before tracking any package status.

**What kind of services does `list_contract_services` return?**
The tool returns a list of all postage service codes and their names that are currently active under your specific contract. This helps you know exactly which shipping options, like PAC or SEDEX, you can calculate rates for.

**If I use `lookup_cep` with an invalid Brazilian ZIP code (CEP), what error do I receive?**
The MCP returns a specific error message that tells you the CEP is malformed or does not correspond to any registered address in the system. This lets your agent know immediately that the input data needs correction.

**What information can `list_unit_types` provide about post office locations?**
`list_unit_types` gives you a reference list of all official Correios unit categories. It’s useful for understanding the type of facility—like a main branch or a small pickup point—before searching for nearby units.

**Can my AI automatically track a package just by providing the tracking code?**
Yes! Use the `track_object` tool with the tracking code (e.g., 'QI123456789BR'). Your agent will retrieve the current status, location, and the full history of logistics events.

**How do I calculate shipping prices for PAC or SEDEX?**
Use the `calculate_shipping` tool with the origin and destination CEPs, along with the weight and dimensions of the package. The agent will return the estimated price and delivery deadline.

**Can I retrieve the full address details from a zip code (CEP)?**
Yes! The `search_cep` tool allows your agent to fetch the street name, neighborhood, city, and state associated with any valid Brazilian zip code.