Skip to main content
Glama
mercadolibre-seller-mcp

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.