mercadolibre-seller-mcp
README.md
# mercadolibre-seller-mcp
**An MCP server that lets an AI assistant run your MercadoLibre seller account:** create and edit listings,
see what you sold and what you bought, answer buyer questions and check fees, all in natural language.
> Unofficial community project, not affiliated with MercadoLibre. MercadoLibre's own MCP server
> (`mcp.mercadolibre.com`) only searches the API documentation. This one works with the seller APIs
> using **your own** OAuth token, on your machine.
## What you can ask your assistant
- "What did I sell in the last 30 days, and how much was left after fees?"
- "What have I bought on MercadoLibre this quarter?"
- "Show my active listings and pause the one with no stock."
- "Create a listing for this product, draft the description, and show me a preview first."
- "Are there unanswered buyer questions? Draft replies."
- "What is the fee for a 25,000 ARS item in this category?"
## Tools
| Tool | Type | What it does |
|---|---|---|
| `my_account` | read | Seller id, nickname, reputation |
| `list_items`, `get_item` | read | Your listings / full details of one (description, attributes, photos, shipping) |
| `sales` | read | Your sales for N days: orders, per-item totals, revenue, marketplace fees |
| `my_purchases` | read | Your own purchases as a buyer for N days |
| `questions` | read | Buyer questions on your listings |
| `calc_fee` | read | Marketplace fee and net amount for a price / category / listing type |
| `suggest_category`, `category_attributes` | read | Find a category from a title; list its (required) attributes |
| `create_listing` | **write** | Create a listing with photos and description |
| `update_listing` | **write** | Price, stock, pause/activate, shipping mode, description, extra photos |
| `answer_question` | **write** | Public answer to a buyer question |
## Safety model
- **Write tools are dry-run by default.** They return a preview; nothing changes until you pass `apply=true`.
- `create_listing` **requires an explicit `shipping`** (`personal` = arranged with the buyer, or `mercadoenvios`),
so the assistant has to ask you instead of guessing.
- Listings **cannot be closed or deleted** through this server (irreversible), only paused/activated.
- Answers containing Cyrillic are rejected (they would be published to buyers as typed).
- Tokens are never returned or logged. They live in a local file (`chmod 600` where supported).
- Runs locally over stdio. No third party sees your token or data.
## Setup
1. **Create an app** in your country's MercadoLibre developers portal (for Argentina:
developers.mercadolibre.com.ar). Set a redirect URI and enable read/write for items, orders and
pre/post-sale communications (questions).
2. **Install:** `pip install -r requirements.txt` (Python 3.10+).
3. **Configure:** copy `.env.example` to `.env` and fill `MELI_CLIENT_ID`, `MELI_CLIENT_SECRET`,
`MELI_REDIRECT_URI`, and `MELI_SITE_ID` (default `MLA`; also `MLB`, `MLM`, `MLC`, `MCO`, `MLU`, `MPE`).
4. **Authorize once:** `python auth.py`, open the link, approve, paste the `code` from the redirect URL.
Tokens are saved to `~/.meli-seller-mcp/tokens.json` (override with `MELI_TOKENS_PATH`) and refreshed automatically.
5. **Check:** `python server.py --selftest` prints your account.
## Connect to an MCP client
Claude Code / Claude Desktop / Cursor (`.mcp.json` or the client's MCP settings):
```json
{
"mcpServers": {
"mercadolibre-seller": { "command": "python", "args": ["/absolute/path/to/server.py"] }
}
}
```
## Notes and limitations
- Title, description, attributes and answers go to the marketplace exactly as written: use the site's language.
- Some categories need `family_name` instead of `title`; pass `family_name` for those.
- Free listing quotas, mandatory Mercado Envios in some categories and API permissions differ by site and
account; API errors are returned as-is.
- Public MercadoLibre endpoints change over time. If a call fails with 403, check the app's permissions.
- Not covered yet: shipping labels, claims/returns, invoices, ads, bulk edits.
## Project layout
`server.py` registers tools; `tools_read.py` / `tools_write.py` hold the logic; `ml.py` is a thin API facade;
`meli_client.py` handles OAuth and HTTP; `auth.py` is the one-time authorization helper.
## License
MIT. Use at your own risk: you are responsible for what is published under your seller account.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues