avito-mcp

# avito-mcp

[![npm version](https://img.shields.io/npm/v/avito-mcp.svg)](https://www.npmjs.com/package/avito-mcp)
[![npm 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-212_passing-brightgreen)](./test)
[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript&logoColor=white)](./tsconfig.json)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![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 score](https://glama.ai/mcp/servers/elchin92/avito-mcp/badges/score.svg)](https://glama.ai/mcp/servers/elchin92/avito-mcp)
[![GitHub stars](https://img.shields.io/github/stars/elchin92/avito-mcp?style=social)](https://github.com/elchin92/avito-mcp/stargazers)
[![Avito API snapshot](https://img.shields.io/badge/Avito_API_snapshot-2026--05--25-orange)](./swaggers)

> **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. **141 Avito API tools** + **7 local/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 →](./README.ru.md)**

<a href="https://glama.ai/mcp/servers/elchin92/avito-mcp"><img width="380" height="200" src="https://glama.ai/mcp/servers/elchin92/avito-mcp/badges/card.svg" alt="avito-mcp MCP server" /></a>

> **New in v1.1.0** — a security sweep of 7 audit-found fixes: atomic idempotency (no double-spend race), credential-bypass closed, webhook-redirect exfiltration locked down, oversized-response streaming, hardened hard-confirmation, and confirmation-gated image uploads. Full history in the [CHANGELOG](./CHANGELOG.md).

---

## 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](#remote-mcp-over-http-oauth-21) 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](https://www.avito.ru/professionals/api): `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](#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 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](#avito-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](#remote-mcp-over-http-oauth-21) 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](https://modelcontextprotocol.io/clients).

---

## What's included — up to 148 tools

| Configuration | Tools visible |
|---|---|
| Default (`AVITO_MCP_MODE=full_access`, no opt-ins) | **144** |
| + `AVITO_MCP_EXPOSE_AUTH_TOOLS=1` | 147 (+3 auth) |
| + `AVITO_MCP_ALLOWED_UPLOAD_DIRS=…` | 145 (+1 upload) |
| + Both opt-ins | **148** |
| `AVITO_MCP_CONFIRMATION_MODE=off` | −3 (hides meta_*_action) |
| `AVITO_MCP_MODE=read_only` | ~82 (only `risk=read`) |
| `AVITO_MCP_MODE=guarded` | ~125 (adds `write`, hides `money`/`public`) |

141 tools wrap Avito API endpoints; 7 are local meta tools — `meta_get_rate_limits`, three `meta_*_action` tools for the [confirmation flow](#security), plus `meta_health`, `meta_auth_status` and `meta_capabilities` for introspection. The authoritative inventory lives in [`dist/manifest.json`](./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.

<details>
<summary>📋 <b>Listings</b> — 11 tools (items_*)</summary>

- `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
</details>

<details>
<summary>💬 <b>Messenger</b> — 16 tools (messenger_*)</summary>

- `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](#avito-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
</details>

<details>
<summary>📦 <b>Orders</b> — 12 tools (orders_*)</summary>

- `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)
</details>

<details>
<summary>🔄 <b>Autoload</b> — 17 tools (autoload_*)</summary>

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_co