# Correios API MCP

> Correios API provides direct access to Brazilian postal services data. You can track any object using its tracking code or calculate accurate shipping costs and estimated delivery deadlines for various services like SEDEX and PAC.

## Overview
- **Category:** ecommerce
- **Price:** Free
- **Tags:** correios, brazil-logistics, tracking-api, shipping-calculator, postal-service

## Description

Need to handle logistics queries in Brazil? This MCP connects your agent directly to the official Correios REST infrastructure, letting you automate tasks that used to require multiple website visits. Instead of switching between tabs to check status or calculate quotes, your AI client handles it all within the chat interface. For instance, if a customer asks for a tracking update, your agent can fetch the history instantly. If they ask how much an item will cost to ship, the system simulates the price and deadline using weight and zip code details. This keeps conversations flowing and provides instant answers without manual lookups. By connecting this service via Vinkius, you get reliable access to Brazilian logistics data right where your workflow is happening.

## Tools

### calculate_price_deadline
Estimates both the cost and delivery timeline for a package between two Brazilian zip codes, given weight and dimensions.

### track_object
Fetches the complete status history and current location details for any specific postal tracking code.

## Prompt Examples

**Prompt:** 
```
Track the object with code NL123456789BR.
```

**Response:** 
```
I've checked the status for NL123456789BR. It was posted on Oct 24th and is currently 'In Transit' to the distribution center in São Paulo.
```

**Prompt:** 
```
Calculate SEDEX shipping from 01001-000 to 22041-001 for a 500g box (20x15x10cm).
```

**Response:** 
```
Using `calculate_price_deadline`, the estimated price for SEDEX is R$ 24.50 with a delivery deadline of 1 business day.
```

**Prompt:** 
```
What is the current status of my package AA987654321BR?
```

**Response:** 
```
The package AA987654321BR was 'Delivered' today at 2:30 PM in Curitiba.
```

## Capabilities

### Determine object status
Retrieves the full history of events and current location for any valid postal tracking code.

### Estimate shipping costs
Calculates the precise monetary price for various services based on package dimensions, weight, and destination codes.

### Calculate delivery deadlines
Provides an estimated number of business days until the package is expected to arrive at its destination.

### Automate logistics quoting
Runs simulated shipping price and deadline calculations for e-commerce checkout processes or support chats.

## Use Cases

### A client asks for tracking status.
The Support Agent uses `track_object` with the provided code. The agent instantly replies, stating the item's current location and its last recorded event (e.g., 'In Transit to São Paulo').

### A customer needs a shipping quote.
The E-commerce system calls `calculate_price_deadline`, passing the product dimensions, weight, and zip codes. The response is structured data confirming the exact price and estimated delivery window.

### Logistics team plans regional shipments.
A Logistics Manager uses the MCP to test multiple scenarios via `calculate_price_deadline`. This allows them to compare costs for SEDEX vs. PAC services across different regions before confirming a quote.

### Batch update of delivery status.
The agent processes several codes using `track_object` in quick succession, compiling a summary report that lists the current state and last known location for all items.

## Benefits

- Eliminate manual lookups. Instead of opening a browser and pasting tracking numbers, your agent runs the `track_object` tool to give you instant status updates right in the conversation.
- Improve customer experience by providing real-time quotes. You can run `calculate_price_deadline` to estimate shipping costs and deadlines immediately when a customer asks about postage.
- Streamline e-commerce operations. Support teams use this MCP to gather full shipment history, so they never have to promise a status update they can't verify instantly.
- Gain efficiency with complex calculations. The `calculate_price_deadline` tool handles the geometry: weight, dimensions, and origin/destination zip codes—you just feed it the variables.
- Reduce support time. By giving agents access to this data, you drastically cut down on the back-and-forth required when a customer simply needs to know where their package is.

## How It Works

The bottom line is, you tell your agent what data you need, and it executes the logistics query using the live API credentials provided.

1. Subscribe to this MCP on Vinkius and enter your specific Correios API credentials (User and Password).
2. Your AI client uses those stored credentials to authenticate the connection with the official Correios system.
3. The agent then sends a structured request, either asking for an object's status or providing shipping parameters for calculation.

## Frequently Asked Questions

**Can I track an object using the `track_object` tool?**
Yes, you can use `track_object` to fetch the full history and current status of any package. Just provide a valid Brazilian tracking code.

**How do I calculate shipping costs with `calculate_price_deadline`?**
You must pass three things: the origin zip, the destination zip, and the full dimensions/weight of the package. This ensures an accurate quote for any service.

**Does this MCP handle international tracking?**
No, this MCP is designed specifically for Brazilian postal services (Correios). For international shipments, you'll need a different API tool.

**What if I change the dimensions? Do I run `calculate_price_deadline` again?**
Yep. Because shipping rates are highly sensitive to package size, always re-run `calculate_price_deadline` whenever you adjust any dimension or weight.

**What credentials are required before running `track_object`?**
You must provide your registered Correios User and Password to connect. You'll enter these details during the initial setup phase on Vinkius. This ensures your AI client can authenticate with the official API endpoints.

**If I run `track_object` with an invalid or non-existent postal code, what response should I expect?**
The tool will return a structured error message indicating that the tracking number is invalid. This prevents guesswork and gives your agent a clear status to report back to the user.

**Are there any limits on how often I can run the `calculate_price_deadline` tool in a single day?**
Yes, like all official APIs, there are rate limits. If you send too many requests quickly, you'll receive an API throttle error. It’s best practice to batch similar calculations or implement a short delay between calls.

**When using `calculate_price_deadline`, must I specify the shipping service (like SEDEX or PAC)?**
Absolutely, you must name the specific service type. The price and deadline change drastically depending on whether it's a standard PAC shipment or an express SEDEX package.

**What information do I need to calculate a shipping price?**
You need to provide the origin and destination ZIP codes (CEP), the service code (e.g., 04014 for SEDEX), weight, package format, and dimensions (length, height, width) using the `calculate_price_deadline` tool.

**Can I track multiple objects at once?**
The `track_object` tool currently processes one tracking code per request to ensure detailed event history for that specific item.

**What is the 'idLote' field in the shipping calculation?**
The `idLote` (Batch ID) is a required identifier for the Correios API request. It can be any string or number used to identify your specific calculation request in their logs.