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. 138 Avito API tools + 7 local/meta tools = up to 145 MCP tools across 18 official Avito APIs, one npx command to install.

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

New in v0.7.5 — tool-definition quality pass: every tool's description and parameters rewritten for agent legibility (purpose, usage, side-effects, disambiguation), honest destructiveHint on irreversible actions, and a glama.json listing claim. See the CHANGELOG for full history.

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

138 wrap Avito API endpoints; 7 are local meta tools: meta_get_rate_limits, three meta_*_action for the confirmation flow (when enabled), plus meta_health, meta_auth_status, meta_capabilities (v0.7.0). Run npm run generate:manifest to dump the full inventory to dist/manifest.json.

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

• 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

• • 6 deprecated v1 endpoints, 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 (v0.6.0)

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.

Prompts

Structured tool outputs

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

• Objects → { status, ...data }

• Arrays → { status, items, count }

• Binary (PDF labels, audio) → { status, mimeType, sizeBytes, base64 }

• Errors → { error_kind, status?, request, body? } with isError: true

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". Clients that adjust verbosity via logging/setLevel work as expected. Pino → stderr is preserved.

Universal safety primitives (v0.7.0)

These are opt-in primitives meant to 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 (tool, key, hash(args)):

• 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 | 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 no longer 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. Stale locks (dead PID, ancient timestamp) are reclaimed automatically. 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 --health               # print JSON health snapshot and exit

--health does not connect stdio transport — ideal for Docker / Kubernetes / supervisord health probes:

healthcheck:
  test: ["CMD", "avito-mcp", "--health"]
  interval: 30s

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:

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

Microsoft added MCP support to Copilot Chat in 2025. Create .vscode/mcp.json in your workspace or use the Command Palette → "MCP: Add Server". Same Quick Start JSON.

OpenAI's CLI assistant supports MCP via ~/.codex/config.toml:

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

Settings → Tools → AI Assistant → MCP → Add server. Fill the same fields (command npx, args -y avito-mcp, env variables). Applies to IntelliJ IDEA, PyCharm, WebStorm, GoLand, Rider.

Block's open-source CLI agent. Add via goose configure → MCP server → paste the Quick Start JSON. Config lives in ~/.config/goose/config.yaml.

Both are forks of Cline and use the same config format and path patterns — replace saoudrizwan.claude-dev in the path with the fork's extension ID (rooveterinaryinc.roo-cline or kilocode.kilo-code). JSON is identical.

Edit librechat.yaml:

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

Settings → MCP Servers → Add. UI fields: name avito, command npx, args -y avito-mcp, env vars same as above.

The server speaks stock stdio MCP. Universal parameters:

• command: npx

• args: ["-y", "avito-mcp"]

• env: { Client_id, Client_secret, Profile_id }

• transport: stdio

Browse the MCP clients directory for new ones.

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-layer safety model (every layer opt-in via env vars; defaults preserve v0.1.x behaviour for trivial calls but harden everything destructive):

  • AVITO_MCP_MODE (read_only / guarded / full_access) — registration-time gate. Hidden tools never appear in tools/list. read_only ≈ 80 tools, guarded adds writes (~123 tools), full_access is the full 138 Avito + 7 meta (+ opt-in extras).

  • AVITO_MCP_ALLOW_TOOLS / AVITO_MCP_DENY_TOOLS — per-tool gating. Deny wins over allow.

  • AVITO_MCP_CONFIRMATION_MODE (off / money_public (default) / all_destructive) — runtime gate. Destructive tools return {requires_confirmation: true, confirmation_id: ...}; agent must call meta_confirm_action to execute. Pending state is in-memory, TTL'd (default 15 min), one-shot.

  • AVITO_MCP_EXPOSE_AUTH_TOOLS (default: 0) — auth_* tools return OAuth tokens; classed as sensitive and hidden by default even in full_access.

  • AVITO_MCP_ALLOWED_UPLOAD_DIRS — messenger_upload_images reads files from disk; without an explicit directory allowlist it doesn't register at all. Path validation uses realpath (symlink-escape proof), extension allowlist (jpg/jpeg/png/webp), size cap (AVITO_MCP_MAX_UPLOAD_MB, default 15), magic-byte sniff with extension cross-check.

• Every tool is tagged with one of five risks (sensitive / read / write / money / public), exposed as MCP ToolAnnotations (readOnlyHint, destructiveHint) and as _meta.risk, and listed in dist/manifest.json. Well-behaved MCP clients warn before destructive calls.

• See docs/safety.md for ready-to-paste configs (analytics-only, customer-support with confirmation, listings-only, full admin) and a frank discussion of what the confirmation flow is and isn't (it's a server-side two-step + audit layer, not a cryptographic human-approval mechanism).

• All 138 Avito 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.