avito-mcp

avito-mcp

将 AI 客户端连接到你的 Avito 账户：读取聊天和统计数据、准备回复，并管理商品和订单。

用日常语言向 AI 客户端提问；它会使用此 MCP 服务调用 Avito 官方 API。涵盖 18 个 API 的 148 个工具，支持买家聊天、商品、统计数据、推广和订单。可在你的电脑或自有服务上运行。

你需要准备一个 AI 客户端和一个拥有 API 访问权限的 Avito 账户。客户端提供模型；本项目提供连接和工具。自动回复和定时报告需要另行配置 Agent 或调度器。

Русская версия → · 文档 · 客户端配置 · 工作流 · 故障排除

**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，通过“设置”→“开发者”→“编辑配置”将此配置合并到 MCP 配置中。对于 Cursor，使用个人的 ~/.cursor/mcp.json。在本地替换这三个占位符，并确保填入内容的配置不会提交到 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 扩展	TOML
ChatGPT 桌面版	设置 → MCP 服务或共享 TOML
ChatGPT 网页版	远程插件设置与限制

这些是文档中列出的配置，并不表示已针对实时 Avito 账户测试过每个客户端/版本。报告兼容性结果时，请附上客户端版本和操作系统。

API 覆盖范围

领域	示例
Messenger	聊天、消息、图片、订阅和 webhook 事件
商品刊登和统计	商品刊登详情、价格、浏览量、联系信息和支出
订单和库存	配送状态、跟踪信息、标签、标记代码和库存
推广	VAS、CPA 出价、预测和推广订单
自动加载	Feed 上传、报告和 ID 映射
账户和其他 API	余额、评价、员工、资费和通话
物流合作伙伴	3PL 配送端点；大多数卖家不需要这些

捆绑的 API 快照涵盖 138 个 Swagger 操作，以及本地和元工具。完整清单包含 148 个工具；默认注册会公开 144 个，因为返回令牌的工具和本地图片上传需要单独选择启用。read_only 在应用允许列表过滤前会公开 80 个工具。请检查 avito://manifest 或构建 dist/manifest.json，以查看准确的名称、架构和风险。

资源包括工具清单、当前配置、速率限制、待确认事项和 webhook 事件。五个内置提示词涵盖每日概览、未读聊天、推广准备、工具说明和安全报告。资源和提示词参考。

安全与重试

• read_only、guarded 和 full_access，以及 AVITO_MCP_ALLOW_TOOLS / AVITO_MCP_DENY_TOOLS，用于控制可用工具。
• dryRun: true 可预览破坏性请求，而不发送请求。它不会预留操作，也不会验证当前账户是否有权执行该操作。
• 默认情况下，涉及资金和面向客户的操作采用两次调用的确认流程。Agent 可以完成这两次调用：这不能证明获得了人工批准。请使用客户端审批，或使用安全配置中所述的单独审批控件。
• idempotencyKey 会在配置的保留期限内，对相同工具和参数进行去重。对于同一预期操作，请重复使用相同的键。如果结果不确定，请先与 Avito 核对，再重试或选择新键。
• 凭据会直接发送给 Avito；本项目不运营代理或遥测系统。工具结果会显示给你的 AI 客户端，并可能根据该客户端的设置发送给其模型提供商。

业务调用会使用真实的 Avito 账户。请从读取和预览操作开始。可直接使用的安全配置介绍了更严格的审批控件、上传边界和恢复方式。

通过 HTTP 提供远程 MCP（OAuth 2.1）

对于托管 Agent 或多个客户端，请在你自己的 HTTPS 域名上使用 Streamable HTTP。设置 AVITO_MCP_TRANSPORT=http、AVITO_MCP_HTTP_PUBLIC_URL=https://mcp.example.com 和强密码 AVITO_MCP_OAUTH_OWNER_PASSWORD，并配置 Avito 凭据。

部署、OAuth、Caddy 和 nginx 配置。bearer 和 none 模式不声称符合 MCP 授权规范；对于会自动发现授权方式的客户端，请使用 OAuth。

Avito webhook 接收器

可选接收器会缓冲收到的 Avito 事件，并通过工具和可订阅资源将其公开。外部 Agent 必须使用这些事件，并决定是否响应。接收器设置。

协议和兼容性

协议修订版本

AVITO_MCP_PROTOCOL_ERA 用于选择 legacy（默认，MCP 2025-11-25）、dual（两个修订版本）或 modern（MCP 2026-07-28）。默认的 stdio 安装会继续提供旧版修订版本；启用新版修订版本需要显式操作。

AVITO_MCP_HTTP_MAX_SESSIONS 和 AVITO_MCP_HTTP_SESSION_IDLE_SEC 仅适用于旧版 2025-11-25。新版 HTTP 使用 AVITO_MCP_HTTP_MAX_INFLIGHT 和 AVITO_MCP_HTTP_MAX_STREAMS。协议详情和限制。

公开工具名称、文档中列出的有效参数、环境变量、资源 URI 和提示词名称均遵循 SemVer。请参阅版本控制详情、从 1.3.x 迁移和 CHANGELOG。

安全

返回令牌的工具和图片上传功能默认隐藏，只有显式启用后才会开放。令牌和运行时状态均存储在本地，并采用受限的文件权限。安全配置、安全策略和私密报告以及运行诊断介绍了相关边界。

从源代码安装

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 传入凭据，或将 AVITO_ENV_FILE 设置为已填写的 .env 文件的绝对路径。项目包含 Dockerfile 和 systemd 安装程序；部署前请阅读运维文档和 .env.example。

贡献者：CONTRIBUTING 介绍了共享工具工厂和验证流程。提交代码 PR 前，请运行 npm run verify:release。CI 会检查类型、测试、覆盖率、软件包安装和部署行为；Avito 实时冒烟测试则需单独显式运行。

本文未涵盖的内容

本项目不包含 Auction、Autostrategy、Autoteka、Jobs、Realty reports 和 Short-term rent API 规范。本项目也不提供模型、托管式 Agent 服务或调度器。请参阅路线图，了解具体的贡献机会。

问题和 Bug 报告：GitHub Issues · 支持。有帮助的贡献包括可复现的 Bug、经过测试的客户端配置，或更清晰的工作流。如果本项目对你有所帮助，点亮 GitHub 星标可以帮助其他 Avito 用户发现它。

MIT。本项目独立运营，与 Avito 无关联。商标和 API 条款声明请参阅 NOTICE。