Avito MCP Server

avito-mcp

Give your AI agents hands and feet on Avito. An 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. 138 Swagger endpoint tools + 3 local/convenience tools + 7 meta tools = up to 148 MCP tools across 18 official Avito APIs. Runs locally over stdio or as a shared remote MCP over HTTP (OAuth 2.1), with a built-in webhook receiver for real-time chat events. One npx command to install.

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

New in v1.2.0 — full security and contract hardening: account-bound tokens, mutation-safe retries, strict OAuth scope/resource and session ownership, operator-locked webhooks, race-safe confirmation/idempotency, descriptor-safe uploads, bounded response/state stores, all-source coverage, and generated OpenAPI contract checks for all 138 endpoint wrappers. See the CHANGELOG for migration notes.

---

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-first — stdio transport by default, your OAuth credentials never leave your machine (optional remote HTTP mode for shared/team deployments)
• 🤖 Built for autonomy — dry-run, idempotency keys, a confirmation flow and risk-tagged tools make it safe to leave an agent running unattended
• ⚡ 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 Connect your AI client):

{
  "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. Pair with the webhook receiver to react the instant a customer writes instead of polling.
• 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 (via AVITO_MCP_ALLOW_TOOLS / safety modes).
• Team / hosted deployment — one remote MCP instance behind OAuth 2.1, shared by several clients and humans.

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 — up to 148 tools

138 tools map one-to-one to bundled Swagger operations, 3 are local/convenience tools, and 7 are meta tools — meta_get_rate_limits, three meta_*_action tools for the confirmation flow, plus meta_health, meta_auth_status and meta_capabilities for introspection. The authoritative, active-policy inventory lives in dist/manifest.json (regenerate with npm run generate:manifest).

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.

• items_get_items_info — list your listings (pagination, status, category filters)
• items_get_item_info — full details of one listing
• items_post_calls_stats — call statistics per item per day
• items_post_vas_prices — promotion service prices for given items
• items_post_item_stats_shallow — basic views/contacts/calls over a period
• items_post_item_analytics — extended analytics with grouping & sorting
• items_post_account_spendings — spend breakdown by service type
• items_update_price ⚠️ — change listing price
• items_put_item_vas ⚠️ — apply one paid VAS service
• items_put_item_vas_package_v2 ⚠️ — apply a VAS package
• items_apply_vas ⚠️ — apply multiple VAS slugs at once

• messenger_get_chats_v2 — list chats (filters: unread, item_ids, chat_types)
• messenger_get_chat_by_id_v2 — details of one chat
• messenger_get_messages_v3 — message history in a chat (paginated)
• messenger_get_voice_files — download URLs for voice messages
• messenger_get_subscriptions — current webhook subscriptions
• messenger_post_send_message ⚠️ — send a real text reply to a customer
• messenger_post_send_image_message ⚠️ — send an image (use upload first)
• messenger_upload_images — multipart upload, returns image_ids
• messenger_delete_message ⚠️ — delete a message
• messenger_chat_read — mark all unread in a chat as read
• messenger_post_blacklist_v2 ⚠️ — block users (with reason codes)
• messenger_post_webhook_v3 ⚠️ — subscribe to push notifications (needs public URL)
• messenger_post_webhook_unsubscribe — unsubscribe
• messenger_get_webhook_events — drain events received by the built-in webhook receiver
• messenger_get_webhook_status — receiver stats: retained / total received / last received
• messenger_register_webhook ⚠️ — subscribe the configured public URL with Avito in one call

• orders_get_orders — list orders with filters
• orders_get_courier_delivery_range — available courier time slots
• orders_download_label — fetch generated label PDF
• orders_markings ⚠️ — submit "Честный знак" (mandatory product marking)
• orders_accept_return_order ⚠️ — choose Russian Post office for return
• orders_apply_transition ⚠️ — change order status (confirm/ship/cancel)
• orders_check_confirmation_code — verify pickup code
• orders_cnc_set_details ⚠️ — click-and-collect order details
• orders_set_courier_delivery_range ⚠️ — pick a courier time slot
• orders_set_tracking_number ⚠️ — set carrier tracking number
• orders_generate_labels — generate labels (≤100 orders)
• orders_generate_labels_extended — generate labels (≤1000 orders)

XML/YML/CSV feed uploads, report retrieval, ID mapping, category schema lookup. Includes both v1 (deprecated, kept for compatibility) and v2/v3.

• autoload_upload ⚠️ — trigger a feed upload (rate-limited to 1/hour)
• autoload_get_profile_v2, autoload_create_or_update_profile_v2 ⚠️ — manage feed profile
• autoload_get_reports_v2 — list upload reports with pagination
• autoload_get_report_by_id_v3, autoload_get_last_completed_report_v3 — report details
• autoload_get_report_items_by_id, autoload_get_report_items_fees_by_id — per-item results
• autoload_get_ad_ids_by_avito_ids, autoload_get_avito_ids_by_ad_ids — ID mapping
• autoload_user_docs_tree, autoload_user_docs_node_fields — category schema reference
• • 5 legacy endpoints (deprecated v1 and early v2), kept under their original names for compatibility

Avito's logistics partner API for delivery service providers. Most users will never call these — they're for shipping companies integrating with Avito Delivery. Includes both production endpoints and sandbox endpoints for partner testing. Full list in the source: src/domains/delivery.ts.

• BBIP promotion (7) — promotion_get_bbip_forecasts_by_items_v1, promotion_create_bbip_order_for_items_v1 ⚠️, promotion_get_order_status_v1, …
• CPA (11) — chats/calls by time, balance v2/v3, complaints, phone info — cpa_*
• CPA target action (5) — cpa_target_get_bids, cpa_target_save_auto_bid ⚠️, cpa_target_save_manual_bid ⚠️, …
• CPA auction (2) — cpa_auction_get_user_bids, cpa_auction_save_item_bids ⚠️

• User (3) — user_get_user_info_self, user_get_user_balance, user_post_operations_history
• Stock (2) — stock_get_stocks_info, stock_update_stocks ⚠️
• Hierarchy (5) — sub-accounts, employees, item assignment (multi-employee setups)
• Reviews (4) — reviews_get_reviews_v1, reviews_create_review_answer_v1 ⚠️, reviews_remove_review_answer_v1 ⚠️, reviews_get_ratings_info_v1

• Tariffs (1) — transport-category tariff reference
• TrxPromo (3) — transactional promotion: commissions / apply / cancel
• CallTracking (3) — call records and audio retrieval
• Messenger discounts (5, beta) — bulk discount campaigns in chats

• Auth (3) — auth_get_access_token (debug; the server manages tokens automatically), auth_get_access_token_authorization_code, auth_refresh_access_token_authorization_code
• Meta (1) — meta_get_rate_limits — observe X-RateLimit-* across all domains

⚠️ 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.

---

MCP resources & prompts

Beyond tools, the server exposes MCP resources (data your agent can fetch without an API call) and prompts (canned workflows that orchestrate the right tools in the right order).

Resources

Subscribe to avito://state/pending-actions and your client sees every create/confirm/cancel/expire in real time — perfect for UIs that want a "things waiting for human" indicator. Subscribe to avito://webhook/events and the client is notified the moment Avito delivers a new chat event.

Prompts

Structured tool outputs

Every tool returns structuredContent alongside the text block — clients can parse Avito responses as JSON without regex:

• Objects → { status, ...data, http_status }; legacy/API-owned status is preserved, while http_status is always the HTTP code
• Arrays → { status, http_status, items, count }
• Binary (PDF labels, audio) → { status, http_status, mimeType, sizeBytes, base64 }; text content also keeps base64 for pre-2025-06-18 MCP clients
• Errors → { error: { type, message, retryable, retryAfter?, httpStatus? }, error_kind } with isError: true — see Structured error taxonomy

MCP logging

Selected pino events (mode changes, hidden-tool reports, confirmation lifecycle, rate-limit warnings) are forwarded to the client as notifications/message with logger: "avito-mcp", with sensitive fields censored. Clients that adjust verbosity via logging/setLevel work as expected. Pino → stderr is preserved.

---

Universal safety primitives

Opt-in primitives that make the package safe to use in any automation context — manual chat, scheduled jobs, multi-agent runtimes, server farms — without committing to a specific orchestrator or backend.

Dry-run

Every destructive tool (risk: write | money | public) accepts an optional dryRun: boolean parameter. When true, the tool returns a structured preview of the HTTP request it would have made — no call to Avito. Useful both for human inspection ("what is the agent about to do?") and for agents that want to think before acting.

{
  "name": "items_update_price",
  "arguments": { "item_id": 12345, "price": 1400, "dryRun": true }
}

→ structuredContent: { dryRun: true, operation: { tool, method, path, ... }, request_preview: { ... } } and fetch is never called.

You can flip the default for the entire server: AVITO_MCP_DRY_RUN_DEFAULT=true or --dry-run. Then every destructive tool short-circuits unless the agent explicitly passes dryRun: false.

Idempotency

Every destructive tool also accepts an optional idempotencyKey: string. The server keeps an in-memory ledger keyed by bounded SHA-256 fingerprints of (tool, key) plus hash(args); long keys are never retained verbatim:

• First call with a key: executes, caches the result.
• Repeat call with the same key + identical args within TTL: returns the cached result, marked structuredContent.idempotent_replay: true. No second HTTP call.
• Repeat call with the same key + different args: returns a structured IdempotencyConflictError (the dedupe contract was violated).

This is the simplest reliable defence against duplicate sends after retries, crashes, or race conditions between concurrent agents. TTL via AVITO_MCP_IDEMPOTENCY_TTL_SEC (default 1 hour).

Structured error taxonomy

All errors return both human text and a machine envelope:

{
  "isError": true,
  "structuredContent": {
    "error": {
      "type": "AVITO_RATE_LIMIT",
      "message": "Avito API 429 for POST ...",
      "retryable": true,
      "retryAfter": 60,
      "httpStatus": 429
    }
  }
}

type ∈ AVITO_BAD_REQUEST | AVITO_UNAUTHORIZED | AVITO_FORBIDDEN | AVITO_NOT_FOUND | AVITO_RATE_LIMIT | AVITO_SERVER_ERROR | AVITO_API_ERROR | NETWORK_ERROR | TIMEOUT | CONFIG_ERROR | INTERNAL_ERROR.

Agents can branch on retryable and retryAfter programmatically — no regex over English text.

Health / auth / capabilities meta-tools

All three have strict outputSchema (zod) — clients can validate against the contract.

Cross-process token lock

If you run multiple avito-mcp processes against the same token file (cron + chat + CLI), they never hit Avito's /token endpoint in parallel. The first to acquire {tokenFile}.lock refreshes; the rest wait, then read the freshly-refreshed token from disk. Ownership-checked leases reclaim dead/corrupt locks without stealing a live process's lock. Tunable via AVITO_MCP_TOKEN_LOCK_TIMEOUT_MS (default 30s).

CLI flags

Convenience shortcuts that translate to env vars (env wins if both set):

avito-mcp --readonly             # AVITO_MCP_MODE=read_only
avito-mcp --guarded              # AVITO_MCP_MODE=guarded
avito-mcp --dry-run              # AVITO_MCP_DRY_RUN_DEFAULT=true
avito-mcp --no-confirmation      # AVITO_MCP_CONFIRMATION_MODE=off
avito-mcp --http | --both        # AVITO_MCP_TRANSPORT=http | both
avito-mcp --health               # print JSON health snapshot and exit

--health does not start the server; it is a local configuration/capability diagnostic, not a liveness probe for an already running process. The bundled Docker image checks PID 1 in stdio mode and the live /readyz endpoint in HTTP/webhook mode. For Kubernetes or a supervisor, probe:

/readyz returns 200 only while the listener is open, HTTP-mode Avito credentials are complete, the token state directory is writable, the OAuth store lease is healthy, and configured webhook persistence has not failed. Its public body remains only { "ok": boolean }.

httpGet:
  path: /readyz
  port: 3000

---

Remote MCP over HTTP (OAuth 2.1)

By default avito-mcp speaks stdio — perfect for a local client. It can also run as a remote MCP server: the same 148 tools served over the network via Streamable HTTP, so a hosted agent, a team, or a phone-based client can connect to one shared instance. Access is gated by OAuth 2.1 (authorization-code + PKCE + Dynamic Client Registration), with a human-in-the-loop consent screen.

Turn it on

AVITO_MCP_TRANSPORT=http            # stdio (default) | http | both   (CLI: --http)
AVITO_MCP_HTTP_HOST=127.0.0.1       # loopback by default; TLS is the proxy's job
AVITO_MCP_HTTP_PORT=3000
AVITO_MCP_HTTP_PUBLIC_URL=https://mcp.example.com   # your public TLS domain, NO trailing slash
AVITO_MCP_HTTP_AUTH=oauth           # oauth (default) | bearer | none
AVITO_MCP_OAUTH_OWNER_PASSWORD=…    # REQUIRED, random, at least 32 bytes
# Client_id / Client_secret / Profile_id as usual (the Avito credentials the remote server acts with)

both runs stdio and HTTP at once — handy when one process serves a local client and a remote one simultaneously.

How the OAuth flow works

1. A client hits /.well-known/oauth-protected-resource/mcp (the RFC 9728 path-suffixed URL the 401's WWW-Authenticate header points to), discovers the authorization server, and reads /.well-known/oauth-authorization-server.
2. The client self-registers via Dynamic Client Registration (POST /register) — no manual client setup.
3. It runs authorization-code + PKCE: opens /authorize in a browser.
4. A human approves at /authorize by entering AVITO_MCP_OAUTH_OWNER_PASSWORD. This is the gate — without the owner password no token is ever issued, and the approval endpoint is rate-limited against brute force.
5. The client exchanges the code at /token for a bearer token (TTL AVITO_MCP_OAUTH_TOKEN_TTL_SEC, default 3600s), and that token guards every /mcp request.

Tokens are accepted only with the exact avito:mcp scope and this deployment's exact resource URL; each MCP session is bound to the OAuth principal that initialized it. Consent transactions and authorization codes are one-time and short-lived.

All HTTP / OAuth env vars

Security model. Node binds 127.0.0.1 by default and speaks plain HTTP. TLS is terminated by a reverse proxy (nginx / Caddy) on your domain, which forwards to http://127.0.0.1:3000. Never expose port 3000 directly to the internet. Host/Origin validation protects MCP and OAuth routes. auth=none on a public host is refused unless you set AVITO_MCP_HTTP_ALLOW_NO_AUTH=1.

v1.2.0 migration: OAuth artifacts issued without the exact scope/resource binding are intentionally rejected. Reauthorize affected clients. A configured AVITO_MCP_OAUTH_STORE_FILE is now single-writer; give each concurrent server its own file.

Reverse-proxy snippets (terminate TLS for https://mcp.example.com)

Both proxy the MCP endpoint, the OAuth discovery/flow endpoints, and the webhook path, and preserve the Host header (the OAuth metadata is built from it).

server {
    listen 443 ssl;
    server_name mcp.example.com;

    ssl_certificate     /etc/letsencrypt/live/mcp.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/mcp.example.com/privkey.pem;

    # MCP transport + OAuth (discovery, authorize, token, register, revoke) + webhook receiver.
    location ~ ^/(mcp|\.well-known/oauth-authorization-server|\.well-known/oauth-protected-resource|authorize|token|register|revoke|avito/webhook|healthz|readyz) {
        proxy_pass         http://127.0.0.1:3000;
        proxy_http_version 1.1;

        proxy_set_header   Host              $host;          # preserve Host — OAuth metadata depends on it
        proxy_set_header   X-Forwarded-Proto $scheme;
        proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;

        # Streamable HTTP keeps long-lived responses open:
        proxy_buffering    off;
        proxy_read_timeout 3600s;
    }
}

mcp.example.com {
    # Caddy obtains and renews the TLS cert automatically.
    # Caddy preserves the Host header by default (no header_up needed).
    reverse_proxy /mcp* http://127.0.0.1:3000
    reverse_proxy /.well-known/oauth-authorization-server* http://127.0.0.1:3000
    reverse_proxy /.well-known/oauth-protected-resource*   http://127.0.0.1:3000
    reverse_proxy /authorize* http://127.0.0.1:3000
    reverse_proxy /token*     http://127.0.0.1:3000
    reverse_proxy /register*  http://127.0.0.1:3000
    reverse_proxy /revoke*    http://127.0.0.1:3000
    reverse_proxy /avito/webhook* http://127.0.0.1:3000
    reverse_proxy /healthz* http://127.0.0.1:3000
    reverse_proxy /readyz*  http://127.0.0.1:3000
}

Quicker: bearer mode

If you control both ends and don't need the full OAuth dance, set AVITO_MCP_HTTP_AUTH=bearer and a shared secret:

AVITO_MCP_TRANSPORT=http
AVITO_MCP_HTTP_PUBLIC_URL=https://mcp.example.com
AVITO_MCP_HTTP_AUTH=bearer
AVITO_MCP_HTTP_AUTH_TOKEN=long-random-secret,another-secret   # one or more, comma-separated

Clients then send Authorization: Bearer long-random-secret to /mcp. The same reverse-proxy config applies.

---

Avito webhook receiver

Polling messenger_get_chats_v2 works, but for real-time reactions (reply the instant a customer writes) Avito can push events to you. The server ships a built-in receiver: point Avito at a secret URL and every event is buffered for your agent to read.

This works even in pure stdio mode — Avito only needs a public URL to POST to; your MCP client never touches it. (If AVITO_MCP_TRANSPORT=stdio and a webhook secret is set, the server still starts a tiny HTTP listener just for the receiver.)

Turn it on

AVITO_MCP_WEBHOOK_SECRET=…                              # random, at least 32 bytes
AVITO_MCP_WEBHOOK_PUBLIC_URL=https://mcp.example.com    # public base Avito POSTs to (defaults to the HTTP public URL)
# AVITO_MCP_WEBHOOK_PATH=/avito/webhook                 # default
# AVITO_MCP_WEBHOOK_BUFFER=100                          # ring-buffer size (events kept in memory)
# AVITO_MCP_WEBHOOK_LOG_FILE=/var/lib/avito-mcp/webhook-events.jsonl

Avito then delivers to:

POST {AVITO_MCP_WEBHOOK_PUBLIC_URL}{AVITO_MCP_WEBHOOK_PATH}/{AVITO_MCP_WEBHOOK_SECRET}
  → 200 {"ok":true}      (answered in well under Avito's 2-second deadline)

The secret is part of the path, so the URL is unguessable — that's the auth. Generate at least 32 random bytes. The URL must be public HTTPS. Both webhook registration tools accept only the exact receiver URL derived from operator configuration; an agent cannot redirect future messages to an arbitrary host. Their dry-run output redacts the secret URL.

Consuming events

A typical loop: subscribe to avito://webhook/events, and on each notifications/resources/updated read the new event, draft a reply, and (after confirmation) send it with messenger_post_send_message.

---

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:

Create the file if it doesn't exist; otherwise add the avito entry to the existing mcpServers block. Fully quit Claude Desktop (system tray) and reopen — a 🔌 avito indicator should appear at the bottom of the chat.

Logs: ~/Library/Logs/Claude/mcp-server-avito.log (macOS).

Easiest — one command:

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

Or add .mcp.json to your project root (use the JSON from Quick Start, plus "type": "stdio"). Verify with claude mcp list.

Path: ~/.cursor/mcp.json (global) or <project>/.cursor/mcp.json (per-project). Use the Quick Start JSON as-is. Reload window after saving (Cmd/Ctrl + Shift + P → "Reload Window").

OpenAI's Desktop app added MCP server support via the Connectors UI. Settings → Connectors → Add custom MCP server → fill in:

• Name: Avito
• Type: stdio
• Command: npx
• Arguments: -y avito-mcp
• Environment variables: Client_id, Client_secret, Profile_id

Path: ~/.codeium/windsurf/mcp_config.json. Use the Quick Start JSON. Alternative: Settings → Cascade → MCP Servers → Add Server (UI).

In VS Code: Cline icon → ⚙️ → MCP Servers → Edit cline_mcp_settings.json.

Use the Quick Start JSON. Cline auto-reloads without VS Code restart.

Add to ~/.continue/config.json:

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

Open Settings (Cmd+,), find the context_servers block:

Documentation truncated — see the full README on GitHub.