avito-mcp

# avito-mcp

[![npm](https://img.shields.io/npm/v/avito-mcp.svg)](https://www.npmjs.com/package/avito-mcp)
[![downloads](https://img.shields.io/npm/dm/avito-mcp.svg)](https://www.npmjs.com/package/avito-mcp)
[![CI](https://github.com/elchin92/avito-mcp/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/elchin92/avito-mcp/actions/workflows/ci.yml)
[![tests](https://img.shields.io/badge/tests-915_passing-brightgreen)](./test)
[![node](https://img.shields.io/node/v/avito-mcp.svg)](package.json)
[![MCP](https://img.shields.io/badge/MCP-compatible-blue)](https://modelcontextprotocol.io)
[![Glama](https://glama.ai/mcp/servers/elchin92/avito-mcp/badges/score.svg)](https://glama.ai/mcp/servers/elchin92/avito-mcp)
[![MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

**An MCP server that hands your Avito account to an AI agent — so you can stop opening it.**
The agent replies to buyers in chat, keeps listings priced and promoted, moves orders through
delivery, files the marking codes, and reads the numbers back to you. Not once, as a demo: on a
schedule, or the moment a customer writes. The 148 tools over Avito's 18 official APIs are how
it does that. The reason to install it is that the daily half hour of clicking stops being yours.

The hard part of that promise is the "without you" half, so most of this server is machinery for
leaving an agent alone with a production account. Spending money takes two calls, not one. Ask any
destructive tool to rehearse and it prints the exact HTTP request instead of sending it. A retry
carrying the same idempotency key replays the first result rather than charging you twice.

**[Русская версия →](./README.ru.md)** · [Upgrading from 1.3.x](./MIGRATION.md) · [CHANGELOG](./CHANGELOG.md)

> **New in v2.0.0** — MCP revision 2026-07-28 is served, switched off behind
> `AVITO_MCP_PROTOCOL_ERA`. OAuth mode now requires an `https` public URL and validates
> registered redirect URIs. Same 148 tools, same schemas, same environment variables. A default
> stdio install upgrades with no changes; [the migration guide](./MIGRATION.md) names who is affected.

---

## Quick start

Node.js 22.12 or newer. No clone, no build, no Docker.

**1.** Get `Client_id`, `Client_secret` and your numeric `Profile_id` from the
[Avito developer portal](https://www.avito.ru/professionals/api). All three are on one page.

**2.** Put this in your MCP client's config. The JSON is identical for every client — only the
file path differs, and those are in [Connect your AI client](#connect-your-ai-client).

```json
{
  "mcpServers": {
    "avito": {
      "command": "npx",
      "args": ["-y", "avito-mcp"],
      "env": {
        "Client_id": "YOUR_CLIENT_ID",
        "Client_secret": "YOUR_CLIENT_SECRET",
        "Profile_id": "YOUR_PROFILE_ID"
      }
    }
  }
}
```

**3.** Restart the client and ask: _"What's my Avito balance and how many unread chats do I have?"_

Two API calls, a real answer, and your credentials never left the machine — stdio is the default
transport, and nothing is proxied through anyone else's server.

---

## Connect your AI client

The snippet above works everywhere. What changes is where you put it.

| Client                    | Where the JSON goes                                                                        |
| ------------------------- | ------------------------------------------------------------------------------------------ |
| Claude Desktop (macOS)    | `~/Library/Application Support/Claude/claude_desktop_config.json`                          |
| Claude Desktop (Windows)  | `%APPDATA%\Claude\claude_desktop_config.json`                                              |
| Claude Desktop (Linux)    | `~/.config/Claude/claude_desktop_config.json`                                              |
| Claude Code               | `claude mcp add avito npx -y avito-mcp -e Client_id=… -e Client_secret=… -e Profile_id=…`  |
| Cursor                    | `~/.cursor/mcp.json`, or `<project>/.cursor/mcp.json`                                      |
| Windsurf                  | `~/.codeium/windsurf/mcp_config.json`                                                      |
| Cline / Roo Code / Kilo   | `…/globalStorage/<extension-id>/settings/cline_mcp_settings.json`                          |
| VS Code (Copilot Chat)    | `.vscode/mcp.json`, or Command Palette → "MCP: Add Server"                                 |
| Zed                       | Settings → `context_servers` (`command: { path, args, env }`)                              |
| Continue                  | `~/.continue/config.json` → `experimental.modelContextProtocolServers`                     |
| Codex CLI                 | `~/.codex/config.toml` → `[mcp_servers.avito]`                                             |
| Goose                     | `goose configure` → MCP server, or `~/.config/goose/config.yaml`                           |
| LibreChat                 | `librechat.yaml` → `mcpServers.avito` (`type: stdio`)                                      |
| ChatGPT Desktop           | Settings → Connectors → Add custom MCP server (type `stdio`, command `npx`)                |
| JetBrains AI Assistant    | Settings → Tools → AI Assistant → MCP → Add server                                         |
| Cherry Studio             | Settings → MCP Servers → Add                                                               |
| Anything else             | stdio, `npx`, `["-y", "avito-mcp"]`, the three env vars                                    |

Claude Desktop needs a full quit from the system tray, not a window close, before it rereads the
file. Its logs are at `~/Library/Logs/Claude/mcp-server-avito.log` on macOS. Cursor needs
"Reload Window"; Cline reloads on its own. New clients appear in the
[MCP client directory](https://modelcontextprotocol.io/clients) faster than this table changes.

---

## What the agent can actually do

Every public endpoint of Avito's 18 OpenAPI specifications is a tool, generated from the bundled
swaggers rather than hand-written, so the coverage is the API's rather than someone's taste.

| Group                    | Tools | What an agent uses it for                                                     |
| ------------------------ | ----: | ----------------------------------------------------------------------------- |
| Messenger                |    16 | Read chats, reply, send images, block, subscribe to push events               |
| Listings                 |    11 | Prices, views/contacts/calls, extended analytics, spend breakdown, paid VAS   |
| Orders                   |    12 | Statuses, courier slots, tracking numbers, labels, "Честный знак" marking     |
| Autoload                 |    17 | XML/YML/CSV feed uploads, per-item reports, ID mapping, category schemas      |
| Promotion & CPA          |    25 | BBIP forecasts and orders, CPA bids, auctions, complaints, balance            |
| Delivery (3PL partner)   |    31 | Avito's logistics API for shipping companies — most sellers never call these  |
| Profile, stock, staff    |    14 | Balance, operations history, stock levels, sub-accounts, reviews and answers  |
| Tariffs, trxpromo, calls |    12 | Tariff reference, transactional promotion, call recordings, chat discounts    |
| Auth & meta              |    10 | Health, capabilities, rate limits, the confirmation flow, raw OAuth tokens    |

The Avito API snapshot in `./swaggers/` is dated 25 May 2026. Avito revises endpoints without
warning; a 404 on a documented method or a missing new one is worth an issue, and the snapshot
gets bumped. The live catalogue with per-tool risk, domain and annotations is the
`avito://manifest` resource, or `dist/manifest.json` after a build — it is generated, not committed.

**How many tools you actually see** depends on configuration. Four of the 148 are opt-in — three
return OAuth tokens, one reads image files off your disk:

| Configuration                                                      | Tools registered |
| ------------------------------------------------------------------ | ---------------: |
| Default (`AVITO_MCP_MODE=full_access`, nothing opted in)           |              144 |
| `+ AVITO_MCP_ALLOWED_UPLOAD_DIRS=…` (enables image upload)         |              145 |
| `+ AVITO_MCP_EXPOSE_AUTH_TOOLS=1` (enables the three `auth_*`)     |              147 |
| Both opt-ins — the full manifest                                   |              148 |
| `AVITO_MCP_MODE=guarded` (hides `money` and `public` risks)        |              119 |
| `AVITO_MCP_MODE=read_only` (only `risk=read`)                      |               80 |
| `AVITO_MCP_CONFIRMATION_MODE=off`                                  |    −3 meta tools |

Hidden tools are never registered, so they do not appear in `tools/list` at all — a model cannot
call what it cannot see. `AVITO_MCP_ALLOW_TOOLS` and `AVITO_MCP_DENY_TOOLS` narrow the set by
name for the swarm case, where the support agent has no reason to hold the promotion budget.

---

## Why you can leave it running

Every tool carries one of five risk classes, and the class decides what happens before the call
goes out: `read` 80, `write` 40, `public` 16, `money` 9, `sensitive` 3. The classes are visible
to the client as MCP `ToolAnnotations` and `_meta.risk`, so an orchestrator can route on them.

**Money and public actions need a second call.** By default (`money_public`) anything that spends
money or is visible to a customer returns `{ requires_confirmation: true, confirmation_id: … }`
instead of executing. The agent — or a human reading over its shoulder — calls
`meta_confirm_action` with that id to let it through. Pending state is durable, account-scoped,
one-shot and expires in 15 minutes; `all_destructive` extends the gate to every write.
`AVITO_MCP_CONFIRMATION_SECRET` turns it into a hard gate, and `AVITO_MCP_APPROVAL_MODE=external`
additionally requires the confirming identity to differ from the one that st