avito-mcp

avito-mcp

AI クライアントを Avito アカウントに接続して、チャットや統計情報の閲覧、返信の準備、出品と注文の管理を行えます。

AI クライアントに普段の言葉で依頼すると、この MCP サーバーが公式 Avito API を呼び出します。18 の API にまたがる 148 個のツールで、購入者とのチャット、出品、統計情報、プロモーション、注文に対応します。お使いのコンピューターまたはご自身のサーバーで実行できます。

AI クライアントと API にアクセスできる Avito アカウントをご用意ください。モデルはクライアントが提供し、このプロジェクトは接続とツールを提供します。自動返信と定期レポートを利用するには、エージェントまたはスケジューラーを別途設定する必要があります。

Русская версия → · ドキュメント · クライアントの設定 · ワークフロー · トラブルシューティング

v2.1.1 の新機能： 手順に沿ったセットアップ、英語とロシア語の完全なワークフローおよびトラブルシューティングガイド、デモと実アカウントの利用方法を明確に説明しています。リリースノート。

次のステップ	ガイド
Avito アカウントなしで動作を確認する	デモを実行する
自分のアカウントを接続する	クイックスタート
すでに使用しているクライアントを設定する	クライアントの設定
デプロイまたはコントリビュートする	運用 · コントリビュート

Avito の認証情報なしで試す

npx -y avito-mcp@2 --demo

デモでは架空のデータを使用します：53 件の出品と 2 件の未読チャットです。 ローカルで実行され、Avito のキーは不要で、Avito へのリクエストも送信しません。レポート、価格のプレビュー、確認、そして再試行しても価格が一度しか変更されないリクエストの流れを確認できます。初回の npx 実行時には npm パッケージがダウンロードされます。ソースから実行する場合は、npm run demo を使用してください。

ご自身の Avito アカウントを使うには、クイックスタートに従い、--demo を省略してください。 通常のサーバー呼び出しでは設定済みのアカウントが使用され、デモデータで置き換えられることはありません。

できること

タスク	まずはこちら	結果
出品状況を確認する	朝のレポート, 分析プロフィール	日付とソース ID を含む残高、出品のアクティビティ、支出
購入者からのメッセージに対応する	未読チャットのトリアージ, メッセンジャープロフィール	優先順位付けされたチャットと返信の下書き。送信は別途確認が必要な操作です
出品価格を変更する	プレビューして確認, 販売者プロフィール	リクエストのプレビュー、保留中の操作、確認すべき結果

プロフィールでは、既存の環境変数を使って用途を絞ったツールセットを公開します。レシピでは、何を依頼するか、どのツールが使われるか、結果をどう確認するかを説明します。

クイックスタート

1. アカウントを準備する

Node.js 22.12+、MCP 対応の AI クライアント、およびアカウントの Avito API 認証情報が必要です。Avito の API アカウントページから Client_id、Client_secret、数値の Profile_id を取得してください。利用できるメソッドは、アカウントの API アクセス権によって異なります。このサーバーをインストールしても、Avito の権限が追加されることはありません。

2. クライアントにサーバーを追加する

Claude Desktopでは、Settings → Developer → Edit Config を使って、これを MCP 設定にマージします。Cursorでは、個人用の ~/.cursor/mcp.json を使用します。3 つのプレースホルダーをローカルで置き換え、値を入力した設定を Git に含めないでください。

{
  "mcpServers": {
    "avito": {
      "command": "npx",
      "args": ["-y", "avito-mcp@2"],
      "env": {
        "Client_id": "YOUR_CLIENT_ID",
        "Client_secret": "YOUR_CLIENT_SECRET",
        "Profile_id": "YOUR_PROFILE_ID",
        "AVITO_MCP_MODE": "read_only"
      }
    }
  }
}

3. 実際の読み取りを確認する

クライアントを再起動し、次のように依頼します。「Avito を使って、アカウント残高とアクティブな出品の最初のページを表示してください。何も変更しないでください。」 正常に動作すると、実際の残高と出品 ID が表示されます。出品がないアカウントの場合は、空のリストが表示されます。この例は read_only で開始します。この設定がない場合、サーバーのデフォルトは full_access のままです。

VS Code、Zed、Codex、ChatGPT では、それぞれ独自のセットアップ形式を使用します。クライアント別の設定をコピーしてから、ワークフローを試してください。例ではメジャーバージョン 2 を固定しています。管理されたデプロイでは、公開済みの特定のバージョンを固定してください。

AI クライアントを接続する

クライアント	すぐにコピーできる設定
Claude Desktop	JSON とセットアップ手順
Cursor	JSON とセットアップ手順
VS Code / Copilot	servers JSON
Zed	context_servers JSON
Codex CLI / IDE extension	TOML
ChatGPT desktop	Settings → MCP サーバーまたは共有 TOML
ChatGPT web	リモートプラグインのセットアップと制限

これらは文書化された設定であり、すべてのクライアント／バージョンが実際の Avito アカウントでテスト済みであることを示すものではありません。互換性の結果を報告する際は、クライアントのバージョンとオペレーティングシステムをお知らせください。

API の対応範囲

ドメイン	例
メッセンジャー	チャット、メッセージ、画像、サブスクリプション、Webhook イベント
出品と統計	出品の詳細、価格、閲覧数、問い合わせ、支出
注文と在庫	配送状況、追跡、ラベル、マーキングコード、在庫
プロモーション	VAS、CPA 入札、予測、プロモーション注文
自動読み込み	フィードのアップロード、レポート、ID マッピング
アカウントとその他の API	残高、レビュー、スタッフ、料金プラン、通話
物流パートナー	3PL 配送エンドポイント。ほとんどの出品者には不要です

同梱の API スナップショットには、138 件の Swagger オペレーションとローカルツールおよびメタツールが含まれています。完全なマニフェストには 148 個のツールがあり、デフォルトの登録では 144 個が公開されます。トークンを返すツールとローカル画像のアップロードには、個別のオプトインが必要なためです。read_only では、許可リストによるフィルタリング前に 80 個が公開されます。正確な名前、スキーマ、リスクを確認するには、avito://manifest を調べるか、dist/manifest.json を作成してください。

リソースには、ツールマニフェスト、アクティブな設定、レート制限、保留中の確認、Webhook イベントが含まれます。組み込みプロンプトは、毎日の概要、未読チャット、プロモーションの準備、ツールの説明、安全性レポートの 5 つです。リソースとプロンプトのリファレンス。

安全性と再試行

• read_only、guarded、full_access と、AVITO_MCP_ALLOW_TOOLS / AVITO_MCP_DENY_TOOLS によって、利用可能なツールを制御します。
• dryRun: true は、破壊的なリクエストを送信せずにプレビューします。アクションの予約や、実際のアカウントでそのアクションを実行する権限の検証は行いません。
• 金銭に関わるアクションや顧客に表示されるアクションでは、デフォルトで 2 回の呼び出しによる確認フローを使用します。エージェントは両方の呼び出しを実行できます。これは人間の承認の証明にはなりません。クライアント側の承認、または安全性の設定で説明されている個別の承認制御を使用してください。
• idempotencyKey は、設定された保持期間内に、同じツールと引数による呼び出しを重複排除します。同じ意図の操作には同じキーを再利用してください。結果が不確かな場合は、再試行したり新しいキーを選んだりする前に、Avito と照合してください。
• 認証情報は Avito に直接送信されます。プロジェクトが運用するプロキシやテレメトリーはありません。ツールの結果は AI クライアントに表示され、そのクライアントの設定に応じてモデルプロバイダーに送信される場合があります。

ビジネス関連の呼び出しでは、実際の Avito アカウントを使用します。まず読み取りとプレビューから始めてください。すぐに使える安全性の設定では、より強力な承認制御、アップロードの境界、復旧方法について説明しています。

HTTP 経由のリモート MCP（OAuth 2.1）

ホスト型エージェントや複数のクライアントで使用する場合は、ご自身の HTTPS ドメインで Streamable HTTP を使用してください。Avito の認証情報とともに、AVITO_MCP_TRANSPORT=http、AVITO_MCP_HTTP_PUBLIC_URL=https://mcp.example.com、強力な AVITO_MCP_OAUTH_OWNER_PASSWORD を設定してください。

デプロイ、OAuth、Caddy、nginx の設定。bearer と none モードは MCP 認可仕様への準拠を主張しません。認可を自動的に検出するクライアントには OAuth を使用してください。

Avito Webhook レシーバー

オプションのレシーバーは、受信した Avito イベントをバッファーに保存し、ツールとサブスクライブ可能なリソースを通じて公開します。外部エージェントはこれらのイベントを消費し、応答するかどうかを判断する必要があります。レシーバーの設定。

プロトコルと互換性

プロトコルのリビジョン

AVITO_MCP_PROTOCOL_ERA は、legacy（デフォルト、MCP 2025-11-25）、dual（両方のリビジョン）、または modern（MCP 2026-07-28）を選択します。デフォルトの stdio インストールでは、引き続き legacy リビジョンが提供されます。新しいリビジョンを有効にするには、明示的な設定が必要です。

AVITO_MCP_HTTP_MAX_SESSIONS と AVITO_MCP_HTTP_SESSION_IDLE_SEC は、legacy 2025-11-25 のみに適用されます。modern HTTP では、代わりに AVITO_MCP_HTTP_MAX_INFLIGHT と AVITO_MCP_HTTP_MAX_STREAMS を使用します。プロトコルの詳細と制限。

公開されているツール名、文書化された有効な引数、環境変数、リソース URI、プロンプト名は、SemVer に従います。バージョニングの詳細、1.3.x からの移行、変更履歴をご覧ください。

セキュリティ

トークンを返すツールと画像のアップロードは、明示的に有効にするまで非表示のままです。トークンとランタイム状態は、アクセス権限を制限してローカルに保存されます。安全性の設定、セキュリティポリシーと非公開の報告、運用診断で、その範囲を説明しています。

ソースからインストールする

git clone https://github.com/elchin92/avito-mcp.git
cd avito-mcp
npm ci
cp .env.example .env
# Fill in your credentials locally.
npm run build:release

node /absolute/path/to/dist/server.js を実行するようにクライアントを設定します。認証情報はクライアントの env を通じて渡すか、入力済みの .env ファイルの絶対パスを AVITO_ENV_FILE に設定してください。Dockerfile と systemd インストーラーが含まれています。デプロイの前に、運用ガイドと .env.example をお読みください。

コントリビューター向け：CONTRIBUTING では、共有ツールファクトリーと検証について説明しています。コードの PR を作成する前に npm run verify:release を実行してください。CI では、型、テスト、カバレッジ、パッケージのインストール、デプロイの動作を確認します。Avito に対するライブのスモークテストは、別途、明示的に実施するチェックです。

このプロジェクトに含まれないもの

Auction、Autostrategy、Autoteka、Jobs、Realty のレポート、Short-term rent の API 仕様は同梱されていません。また、このプロジェクトはモデル、ホスト型のエージェントサービス、スケジューラーも提供しません。具体的な貢献の機会については、ロードマップをご覧ください。

質問やバグ報告：GitHub Issues · サポート。役立つ貢献には、再現可能なバグ報告、テスト済みのクライアント設定、より分かりやすいワークフローなどがあります。このプロジェクトが役立った場合は、GitHub でスターを付けていただくと、ほかの Avito ユーザーにも見つけてもらいやすくなります。

MIT。独立したプロジェクトであり、Avito とは提携していません。商標および API 利用規約に関する注意事項は NOTICE をご覧ください。