Avito Personal MCP

Unofficial, local-first MCP server for personal Avito accounts. It lets an MCP-capable AI client work with your own Avito account through a dedicated browser session — without requiring Avito Developer API credentials.

Why this project exists

Many Avito integrations are built around official developer/business APIs or public listing parsing. Avito Personal MCP is aimed at a different use case: an ordinary user who wants an AI assistant to work with the Avito account they already use in the browser.

The user signs in to Avito manually in a dedicated Chrome profile. The MCP server then attaches to that already authenticated browser over Chrome DevTools Protocol (CDP).

No Avito Developer Client ID or Client Secret is required. The project also does not ask users to provide Avito passwords, SMS/OTP codes, cookies, authorization headers, session tokens, or exported browser storage state.

This makes the project suitable for personal-account workflows such as:

• searching Avito and inspecting individual listings;

• reviewing your own listings;

• reviewing your favorites;

• reading your Avito conversations and message history;

• preparing and explicitly confirming a message before it is sent.

It is not intended to bypass Avito authentication, CAPTCHA, anti-bot controls, account restrictions, or access controls.

Related MCP server: avito-scraper

What it does

Avito Personal MCP exposes a local-first MCP interface over the user's own Avito web session. Authentication remains in the dedicated browser controlled by the user rather than being copied into MCP configuration.

Current MCP tools

Read-only tools:

• avito_selfcheck

• avito_me

• avito_search

• avito_get_listing

• avito_my_listings

• avito_favorites

• avito_chats

• avito_chat_messages

Guarded write tools:

• avito_send_message

avito_send_message is deliberately two-step. The first call only returns a sanitized preview and a short-lived one-time confirmation token. A second call with the same chat id, the same message text, and that token performs one send attempt. The MCP does not automatically retry a send because a retry could create a duplicate message.

Requirements

• Python 3.11, 3.12, 3.13, or 3.14

• Google Chrome or another compatible Chromium browser with CDP support

• a dedicated browser profile for this project

• manual Avito authentication by the user

Installation

Clone the repository and install the package into a virtual environment:

git clone https://github.com/AlexButiev/avito-personal-mcp.git
cd avito-personal-mcp
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install .

Run the MCP server over stdio:

avito-personal-mcp

The console entry point is installed by the package and does not require a repository-local PYTHONPATH.

Dedicated Chrome session

Use a separate Chrome profile. Do not reuse a normal browser profile that also contains banking, email, work, or other sensitive accounts.

On macOS:

open -na "Google Chrome" --args \
  --user-data-dir="$HOME/.avito-personal-mcp/chrome-profile" \
  --remote-debugging-address=127.0.0.1 \
  --remote-debugging-port=9222 \
  "https://www.avito.ru"

Then sign in to Avito manually inside that Chrome window. Do not put Avito credentials, cookies, tokens, or browser storage in MCP client configuration.

CDP security

Keep CDP bound to loopback only (127.0.0.1). Do not expose port 9222 to the LAN, Internet, a public tunnel, or an untrusted container/network namespace. A process that can reach the CDP endpoint can potentially control the attached browser session.

MCP client configuration

The server uses stdio. A generic MCP client configuration looks like this:

{
  "mcpServers": {
    "avito": {
      "command": "/absolute/path/to/.venv/bin/avito-personal-mcp"
    }
  }
}

Use the actual absolute path to the installed console script on your machine. No Avito credentials or session material belong in this configuration.

Chrome and the MCP server are separate processes: start the dedicated Chrome session first, sign in manually if needed, then let the MCP client launch avito-personal-mcp.

Codex and ChatGPT desktop app

On one Mac, the ChatGPT desktop app, Codex CLI, and the Codex IDE extension can share the same ~/.codex/config.toml MCP configuration. Add the installed avito-personal-mcp command there and restart the client; /mcp listing avito verifies that the server can launch. It does not by itself make Avito available in an ordinary ChatGPT conversation. For that experience, install the matching local Avito Personal plugin, start a new ordinary chat, and first confirm a safe avito_selfcheck call before relying on natural-language requests.

Keep avito_send_message on prompt/approval and leave avito_chat_messages on prompt unless you accept Avito's normal behaviour that opening a conversation can mark it read. The configuration and the separate private Secure MCP Tunnel route for ChatGPT on the web are documented in docs/CHATGPT_CONNECTION.md.

Terminal fallback: avito-ai

avito-ai is a small terminal client for the same local MCP surface. It is useful when the AI client cannot yet attach to the MCP server directly, or when you want to copy a compact, structured result into a chat.

avito-ai selfcheck
avito-ai --compact search "мини ПК для HomeLab" --limit 10
avito-ai --compact search "ноутбук" --min-price 10000 --max-price 100000 --sort price_asc --limit 10
avito-ai listing OWN_LISTING_ID
avito-ai listing '<exact-Avito-URL-copied-from-browser-or-search-result>'
avito-ai messages CHAT_ID --limit 20

Search price and sort

avito_search accepts optional min_price, max_price, and sort arguments; the same options are exposed by avito-ai search as --min-price, --max-price, and --sort. Price bounds are non-negative integers and the maximum cannot be below the minimum. Supported sort values are:

• default — Avito's normal result order;

• price_asc / price_desc — lower or higher price first;

• date_desc — newest first;

• discount_desc — larger discount first.

The server uses Avito's rendered price inputs and sort menu, then verifies that the visible result set refreshed. It does not construct undocumented search URLs or pass arbitrary filter selectors from a client. Category-specific filters, location, and pagination are intentionally deferred until each has its own stable UI observation and fail-closed acceptance.

A bare numeric ID is deliberately supported only for one of your own listings: the server first finds its observed URL in the authenticated profile. For another public listing, pass its exact same-origin Avito URL, copied from the browser or returned by avito_search. The server never guesses a listing URL from a numeric ID, because Avito paths include volatile location/category/slug segments and a guessed path is neither reliable nor safe.

The command launches the installed avito-personal-mcp console entry point from the same Python environment, not a repository checkout or a private browser helper. It therefore exercises the packaged MCP path while keeping Chrome, CDP, and all Avito authentication material outside the CLI configuration. The bridge currently exposes read-only commands only; guarded message sends remain available only through the explicit two-phase MCP tool.

To use a different loopback CDP port, set the documented server setting for the individual command; avito-ai forwards only this setting to its child MCP server and does not forward other shell environment values:

AVITO_MCP_CDP_URL=http://127.0.0.1:9333 avito-ai selfcheck

Architecture

MCP client
    |
    v
Avito Personal MCP
    |
    +-- browser/session layer
    +-- profile discovery
    +-- search/listings
    +-- favorites
    +-- chats/messages
    +-- guarded confirmations for writes
    +-- diagnostics
    |
    v
Dedicated user-controlled Chrome session (CDP on loopback)
    |
    v
avito.ru

The implementation prefers browser-visible page state and frontend behavior observed in the user's own authenticated session. It does not guess private endpoints and does not attempt to bypass CAPTCHA or anti-bot controls.

Behavioral caveats

Opening an Avito conversation can cause Avito itself to mark that conversation as read. avito_chat_messages does not intentionally send, edit, delete, react to, or otherwise mutate messages, but normal page navigation can still affect read state.

Browser-driven operations are inherently coupled to Avito's current DOM. The project therefore treats unexpected DOM changes as errors rather than silently pretending an empty result is valid.

Safety principles

• Local-first authentication/session state.

• No Avito Developer API credentials required for the current browser-session workflow.

• No Avito credentials committed to the repository.

• No CAPTCHA bypass, stealth circumvention, or automated OTP handling.

• CDP stays on loopback only.

• Dedicated Chrome profile only; do not use it for unrelated sensitive accounts.

• Read operations are separated from write operations.

• Write operations require explicit confirmation safeguards.

• Message sends are never automatically retried after an irreversible click.

• Logs/tests must not contain passwords, cookies, authorization headers, session tokens, browser storage state, or real private-message fixtures.

See SECURITY.md for the security policy.

Troubleshooting

chrome_unreachable

Confirm the dedicated Chrome instance is running with --remote-debugging-address=127.0.0.1 --remote-debugging-port=9222 and that no firewall/container boundary prevents the local MCP process from reaching it.

no_avito_tab

Open https://www.avito.ru in the dedicated Chrome window.

Authentication unavailable / login redirect

Sign in manually in the dedicated Chrome window. Do not paste credentials, cookies, or tokens into MCP configuration.

DOM mismatch / unavailable data

Avito may have changed its frontend. Fail closed and update selectors only after observing the new browser behavior. Do not guess internal APIs or weaken authentication checks.

Development

Install development dependencies:

python -m pip install -e '.[dev]'

Run local checks:

pytest
ruff check .

GitHub Actions runs sanitized unit tests and Ruff on Python 3.11, 3.12, 3.13, and 3.14 without Avito credentials or a real browser session. Live CDP acceptance is intentionally separate from CI.

Project status

0.1.0rc3 is the current public release candidate. It adds the packaged avito-ai fallback, data-minimized diagnostics, Gate 12 acceptance fixes, and the first stable price/sort search controls to the read-only foundation and guarded message-send path. Browser-driven integrations can still break when Avito changes its frontend, so treat the release candidate as experimental until the final release is promoted.

See CHANGELOG.md for release notes and docs/ROADMAP.md for the capability boundary, safety model, and planned development order. See docs/CHATGPT_CONNECTION.md for the local desktop connection and the private-tunnel runbook for ChatGPT on the web.

License

MIT. See LICENSE.