avito-mcp

Give your AI agents hands and feet on Avito. Local MCP server that lets Claude, Cursor, Cline and any other AI assistant do real work on Avito for you — answer customers, manage listings, run promotions, fulfil orders, analyse stats. 139 tools across 18 official Avito APIs, one npx command to install.

🇷🇺 Русская версия / Russian version →

What it does

Avito is Russia's largest classifieds marketplace (~250M monthly visits). Selling there involves dozens of repetitive operations every day: replying in chats, refreshing listings, applying paid promotion, generating shipping labels, watching stats.

avito-mcp exposes every public Avito API as a tool your AI agent can call. Plug it into your favourite MCP client and your agent can run an entire Avito storefront — autonomously — from natural language.

• 🔌 Universal — works with 15+ MCP clients (Claude Desktop, Cursor, Cline, Continue, Windsurf, Zed, ChatGPT, …)
• 🔒 Local-only — stdio transport, your OAuth credentials never leave your machine
• 🤖 Built for autonomy — pairs naturally with multi-agent runtimes and cron-scheduled agents for hands-off, always-on operation
• ⚡ Zero install — npx -y avito-mcp, no clone/build, no Docker

Quick start (≈90 seconds)

1. Get OAuth credentials from the Avito Developer Portal: Client_id, Client_secret, and your Profile_id (your numeric account ID, shown on the same page).

2. Add this snippet to your MCP client's config (the JSON is the same for every client — only the file path differs, see the next section):

{
  "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 your client. Ask your agent:

"What's my Avito balance and how many unread chats do I have?"

Done. Two API calls, real answer.

Built for autonomous workflows

Most MCP servers are designed to be called by hand from a chat window. avito-mcp is designed to be left running — picked up by multi-agent runtimes and scheduled agents that operate without you watching.

Typical deployment patterns:

• Reactive agent — a Claude/Cursor session permanently open, monitoring chats and replying to customers in your tone of voice.
• Cron-scheduled agent — a runtime fires up your agent every N minutes to triage new orders, top up promotion budgets, refresh stats.
• Multi-agent swarm — separate agents for "support", "promotion", "logistics" each holding only the tools they need.

The stdio transport keeps every credential and API response on your machine. No proxy. No SaaS in the middle.

→ See the full list of compatible runtimes at modelcontextprotocol.io/clients.

What's included — 139 tools

Every public endpoint from Avito's 18 OpenAPI specs is exposed. Click any group to expand.

Avito API snapshot date: 25 May 2026. The bundled swaggers (./swaggers/) reflect Avito's public API as of that date. Avito occasionally adds or revises endpoints — if you spot drift (404 on a known method, new method missing), open an issue and we'll bump the snapshot.

⚠️ marks methods that spend real money or affect live data (price changes, paid promotion, customer-facing messages, blocked users). Safe read-only smoke tools: user_get_user_balance, items_get_items_info, messenger_get_chats_v2, meta_get_rate_limits.

Connect your AI client

The JSON snippet from the Quick Start section above works in every MCP-compatible client — only the path to the config file changes. Pick yours below:

claude mcp add avito npx -y avito-mcp \
  -e Client_id=YOUR_CLIENT_ID \
  -e Client_secret=YOUR_CLIENT_SECRET \
  -e Profile_id=YOUR_PROFILE_ID

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "avito-mcp"],
          "env": { "Client_id": "...", "Client_secret": "...", "Profile_id": "..." }
        }
      }
    ]
  }
}

{
  "context_servers": {
    "avito": {
      "command": {
        "path": "npx",
        "args": ["-y", "avito-mcp"],
        "env": { "Client_id": "...", "Client_secret": "...", "Profile_id": "..." }
      }
    }
  }
}

[mcp_servers.avito]
command = "npx"
args = ["-y", "avito-mcp"]
env = { Client_id = "...", Client_secret = "...", Profile_id = "..." }

mcpServers:
  avito:
    type: stdio
    command: npx
    args: ["-y", "avito-mcp"]
    env:
      Client_id: "..."
      Client_secret: "..."
      Profile_id: "..."

Example prompts

Drop these into your AI client to see what's possible:

📊 Analyse

• "What's my Avito balance and how much did I spend on promotion this month?"
• "Top 10 listings by contacts last week — table with views/contacts/conversion."
• "Find listings whose calls dropped 50%+ compared to the previous week."

💬 Communicate

• "Show me unread chats from the last 24 hours and reply with: 'Hi! Yes, still available, where would you like delivery?'"
• "Read the full conversation in chat X and suggest the best next reply in my tone."

💰 Promote

• "Forecast a 1000₽ BBIP boost on item 12345 — is it worth it?"
• "Set a manual CPA bid of 500₽ on top-10 listings in category 'Electronics'."

📦 Fulfil

• "List all orders with status ready_to_ship and generate labels in a single PDF."
• "For order ABCD, find an available courier slot tomorrow morning."

🤖 Automate

• "Every weekday at 9am, send me Telegram with: balance, new orders count, unread chats count, top promotion spends."
• "If any chat has been unread for 6+ hours, draft a reply and ping me to approve."

What's NOT supported

Avito provides separate APIs for the following verticals — their swagger specs are not bundled:

Also out of scope: authorization_code OAuth flow (no public redirect URI on a local CLI), webhook receiver (needs a public URL), Avito sandbox (no sandbox credentials).

Security

• Local stdio only — no proxy, no remote endpoints, no telemetry.
• Credentials live in your MCP client's env block or local .env. They're never sent anywhere except api.avito.ru.
• OAuth tokens cached in a per-user state directory (chmod 600):
  • Linux: $XDG_STATE_HOME/avito-mcp/token.json (≈ ~/.local/state/avito-mcp/token.json)
  • macOS: ~/Library/Application Support/avito-mcp/token.json
  • Windows: %APPDATA%\avito-mcp\token.json
  • Override with AVITO_TOKEN_FILE. Delete the file to force a refresh.
• Three safety modes via AVITO_MCP_MODE (default: full_access):
  • read_only — only the ~79 read tools register; nothing that writes, spends, or talks to customers is even visible to the agent
  • guarded — adds write tools (~41 more), still hides money and public
  • full_access — all 139 tools, like v0.1.x. Legacy AVITO_SAFE_MODE=read-only still works as a deprecated alias for AVITO_MCP_MODE=read_only.
• Per-tool allowlist / denylist: AVITO_MCP_ALLOW_TOOLS=foo,bar registers only those names. AVITO_MCP_DENY_TOOLS=baz hides them, deny wins over allow. Useful for building purpose-built agent personas — see docs/safety.md for ready-to-paste configs (analytics-only, support, listings-only, full admin).
• Every tool is tagged with one of four risk levels (read / write / money / public), exposed both as MCP ToolAnnotations (readOnlyHint, destructiveHint) and in dist/manifest.json. Well-behaved MCP clients warn before destructive calls.
• All 139 tools hit production — Avito has no sandbox. Write methods cost real money or are visible to real customers. Safe read-only tools for first runs: user_get_user_balance, items_get_items_info, messenger_get_chats_v2, meta_get_rate_limits.
• Found a security issue? Private reporting via SECURITY.md — don't open a public issue.

Community & support

• Bug? Open an issue.
• Question or idea? Start a discussion.
• Need help picking the right tool or setting up your client? See SUPPORT.md.
• Want to contribute? Adding a new Avito swagger takes ~10 minutes — see CONTRIBUTING.md.
• Like the project? Star the repo and tell another Avito seller who uses AI.

Install from source

For development, air-gapped installs, or when you want to modify a tool:

git clone https://github.com/elchin92/avito-mcp.git
cd avito-mcp
npm install
cp .env.example .env       # fill in your credentials
npm run build

Then point your MCP client at:

{ "command": "node", "args": ["/absolute/path/to/avito-mcp/dist/server.js"] }

A template config is in .mcp.json.example.

CLI flags

npx avito-mcp --version    # print the installed version
npx avito-mcp --help       # show env vars + usage

The server has no other flags by design — all knobs are env vars (see --help output).

Contributing

Adding a new Avito swagger? One file in src/domains/ plus one line in src/meta/domain-registry.ts — see CONTRIBUTING.md. The factory in src/core/tool-factory.ts handles HTTP, OAuth, retries, rate-limit observability, error mapping, and Profile_id auto-injection — you'll never write a fetch() call inside a tool.

Issues and PRs welcome.

License

MIT. Not affiliated with Avito.ru. "Avito" is a trademark of its respective owner. Use of the Avito API is subject to Avito's Terms of Service.