AUTO.RIA Used Cars

autoria-mcp

一个 MCP 服务，将 AUTO.RIA 二手车 REST API（auto.ria.com，通过 developers.ria.com）开放给 AI Agent 使用——通过获批的 API，以编程方式让 Agent 便捷地访问乌克兰二手车市场，无需抓取数据。

全部工具均已上线——30 个工具、7 个字典资源和 1 个模板化资源：精选搜索／查询工具（单条和批量车辆详情）、付费统计工具、轻量端点镜像，以及可浏览的字典资源，所有功能均由分层缓存和带类型的异步客户端提供支持。

功能特性

• 精选的高级工具，接受便于用户使用的输入（品牌、车型、地区、年份／价格范围），并为你解析为 AUTO.RIA 的数字 ID。
• 付费统计工具（AI 平均价格、价格随时间变化、VIN 解码）在未设置 AUTORIA_USER_ID 时会立即失败并给出明确错误，避免浪费配额。
• 轻量端点镜像，覆盖各类字典／查询端点。
• 字典资源——以可寻址的 autoria://dict/... 文档形式浏览类别、颜色、地区等内容。
• 积极的分层缓存：大型且变化缓慢的字典会在磁盘上缓存 7 天（首次获取后，名称→ID 的解析不再消耗配额）；变化频繁的搜索／统计响应则仅在内存中短暂缓存。
• stdio 和可流式 HTTP 传输方式。

安装

需要 Python 3.11+。此软件包发布在 PyPI 上；可使用 uvx 运行，无需手动安装：

uvx autoria-mcp

也可以使用 pipx / uv tool 将其安装到工具环境中：

uv tool install autoria-mcp   # or: pipx install autoria-mcp

快速入门：Claude Desktop（无需编写代码）

想通过 Claude 桌面应用使用 AUTO.RIA？按照以下步骤操作即可——无需编程，只需复制粘贴。选择你的平台： macOS · Windows。

macOS

1. 安装 uv（用于运行 autoria-mcp 的小工具）。打开 Terminal 应用，粘贴以下内容，然后按 Enter：

curl -LsSf https://astral.sh/uv/install.sh | sh

（完整说明：https://docs.astral.sh/uv/getting-started/installation/。）

2. 获取免费的 AUTO.RIA API 密钥，网址为 https://developers.ria.com。请妥善保存。 user_id 是可选项——只有使用付费的价格统计工具时才需要。

3. 查找 uvx 的完整路径。 桌面应用无法读取 Terminal 的 设置，因此需要使用完整路径。在 Terminal 中运行：

which uvx

复制输出内容——通常是 /opt/homebrew/bin/uvx（Apple 芯片 Mac）或 /usr/local/bin/uvx（Intel Mac）。

这是设置失败的首要原因。 如果只填 uvx，而不是完整路径，应用会提示找不到它。请始终粘贴 which uvx 输出的完整路径。

4. 打开 Claude Desktop 的配置文件。 在 Claude 应用中：Settings → Developer → Edit Config。这会打开名为 claude_desktop_config.json 的文件（在 macOS 上，文件位于 ~/Library/Application Support/Claude/claude_desktop_config.json）。

5. 添加 autoria 服务。 粘贴下面的代码块。如果文件已有 "mcpServers" 部分，请将 "autoria" 添加到其中，与其他服务并列； 否则粘贴完整内容。替换两个占位值：

{
  "mcpServers": {
    "autoria": {
      "command": "/opt/homebrew/bin/uvx",
      "args": ["autoria-mcp"],
      "env": { "AUTORIA_API_KEY": "paste-your-api-key-here" }
    }
  }
}

• command → 第 3 步中获取的完整路径。
• AUTORIA_API_KEY → 第 2 步中获取的密钥。
• 使用付费工具（平均价格、VIN 查询）时，请将 "AUTORIA_USER_ID": "..." 添加到 env 中——添加时在 API 密钥所在行后加上逗号，例如： "env": { "AUTORIA_API_KEY": "...", "AUTORIA_USER_ID": "..." }。

保存文件。

6. 完全退出并重新打开 Claude。 按 Cmd + Q（仅关闭窗口 是不够的），然后重新打开 Claude。首次启动时会花几秒钟下载工具； 之后即可立即使用。

7. 试用。 可以问 Claude 这样的问题： “使用 autoria 查找基辅的二手 BMW 3 系轿车，并给我看看几辆及其价格。”

使用限制提示： 免费的 AUTO.RIA 密钥每小时大约允许 30 次请求， 每月允许 1000 次请求——因此请提出有针对性的问题，而不是宽泛的问题。

如果重启后 autoria 没有显示，日志文件通常会说明原因：

tail -50 ~/Library/Logs/Claude/mcp-server-autoria.log

最常见的解决方法：使用完整的 uvx 路径（第 3 步），并确保 使用 Cmd + Q 完全退出 Claude。

Windows

Windows 上的流程相同，但命令和一些仅限 Windows 的注意事项与 macOS 不同。

1. 安装 uv（它附带用于运行 autoria-mcp 的 uvx 命令）。打开 PowerShell，运行以下任一命令：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

如果你使用 winget，也可以运行：

winget install --id=astral-sh.uv -e

然后打开一个新的终端窗口，让更新后的 PATH 生效。 （完整说明：https://docs.astral.sh/uv/getting-started/installation/。）

2. 获取免费的 AUTO.RIA API 密钥：访问 https://developers.ria.com。请妥善保存。 user_id 是可选项——仅在使用付费的价格统计工具时才需要。

**3. 找到 uvx.exe 的完整路径。**桌面应用无法读取终端的 PATH，因此需要使用完整路径。在 PowerShell 中运行：

Get-Command uvx | Select-Object -ExpandProperty Source

或者在 命令提示符（cmd）中运行：

where.exe uvx

复制它输出的内容——通常是 C:\Users\<you>\.local\bin\uvx.exe。

在 PowerShell 中，请使用 where.exe，而不是 where。 单独使用 where 时，它是 Where-Object 的别名，无法找到可执行文件。

这是设置失败的首要原因。 如果只使用 uvx 而不提供完整路径，应用会提示找不到它。务必粘贴第 3 步中的完整路径。

4. 打开 Claude Desktop 的配置文件——请使用应用内的按钮。 在 Claude 应用中：设置 → 开发者 → 编辑配置。这会打开与你的安装对应的 claude_desktop_config.json。

不要手动编辑 %APPDATA% 文件。 文档中列出的位置是 %APPDATA%\Claude\claude_desktop_config.json （即 C:\Users\<you>\AppData\Roaming\Claude\claude_desktop_config.json），但 Microsoft Store / MSIX 版本的 Claude 会对该文件夹进行虚拟化——它 实际读取的是 %LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json。 如果编辑普通的 %APPDATA% 副本，你的 MCP 服务就会无提示地加载失败。 编辑配置按钮始终会打开正确的文件——请使用该按钮。

5. 添加 autoria 服务。 粘贴以下代码块。如果文件已有 "mcpServers" 部分，请将 "autoria" 添加在其中，与其他服务并列； 否则粘贴完整内容。在 Windows 上，JSON 中的反斜杠必须加倍（\\）—— 也可以使用正斜杠（C:/Users/you/.local/bin/uvx.exe）：

{
  "mcpServers": {
    "autoria": {
      "command": "C:\\Users\\you\\.local\\bin\\uvx.exe",
      "args": ["autoria-mcp"],
      "env": { "AUTORIA_API_KEY": "paste-your-api-key-here" }
    }
  }
}

• command → 第 3 步中的完整路径，并将反斜杠加倍。
• AUTORIA_API_KEY → 第 2 步获取的密钥。
• 对于付费工具（平均价格、VIN 查询），请在 env 中添加 "AUTORIA_USER_ID": "..." ；添加时要在 API 密钥行后加逗号，例如： "env": { "AUTORIA_API_KEY": "...", "AUTORIA_USER_ID": "..." }。

保存文件。可直接编辑的配置副本位于 examples/claude_desktop_config_windows.json。

不想将密钥保存在配置文件中？省略 env 块，改为在工作目录的 .env 文件中 设置 AUTORIA_API_KEY，或将其设为 Windows 用户/系统环境变量。

6. 完全重启 Claude。 右键点击系统托盘（时钟旁边）中的 Claude 图标， 选择退出——仅关闭窗口还不够——然后重新打开 Claude。第一次启动时， 应用会花几秒钟下载工具；此后启动会立即完成。

7. 试用。 向 Claude 提出类似这样的问题： “使用 autoria 查找 Kyiv 的二手 BMW 3 系汽车，并给我展示几辆及其价格。”

相同的限制和最常见的解决方法仍然适用： 使用完整的 uvx.exe 路径（第 3 步）、通过应用内按钮编辑配置（第 4 步）， 并从系统托盘中完全退出（第 6 步）。日志位于 %APPDATA%\Claude\logs\mcp-server-autoria.log。

配置

所有设置均从环境变量（前缀为 AUTORIA_）或本地 .env 文件中读取。将 .env.example 复制为 .env，并填写你的密钥。

Variable	Default	Description
AUTORIA_API_KEY	— (API 调用必需)	从 https://developers.ria.com 获取的个人 API 密钥。绝不会记录到日志中。
AUTORIA_USER_ID	—	用户 ID，仅付费 POST 端点需要。
AUTORIA_TRANSPORT	stdio	stdio 或 http（可流式传输的 HTTP）。也可使用 --transport。
AUTORIA_HOST	127.0.0.1	HTTP 传输的绑定主机。
AUTORIA_PORT	8000	HTTP 传输的绑定端口。
AUTORIA_BASE_URL	https://developers.ria.com	API 主机（文档中仅说明了生产主机）。
AUTORIA_CACHE_DIR	~/.cache/autoria-mcp	磁盘上的字典缓存位置。
AUTORIA_CACHE_TTL	604800（7 天）	字典缓存的默认 TTL，单位为秒。
AUTORIA_VOLATILE_TTL	600（10 分钟）	易变搜索／统计响应仅保存在内存中的 TTL。
AUTORIA_MEMORY_CACHE_MAX	256	每个内存缓存层的最大条目数（有界 LRU）。
AUTORIA_MAX_RETRIES	3	遇到 429／5xx 时的重试次数（退避 + 完全抖动）。
AUTORIA_BACKOFF_BASE	0.5	基础退避延迟，单位为秒。
AUTORIA_BACKOFF_CAP	8.0	单次退避休眠的最大延迟，单位为秒。
AUTORIA_QUOTA_HOURLY_LIMIT	30	假定的每小时配额；用量接近此值时会发出警告（不会阻止请求）。
AUTORIA_QUOTA_MONTHLY_LIMIT	1000	假定的每月配额；用量接近此值时会发出警告（不会阻止请求）。
AUTORIA_QUOTA_WARN_RATIO	0.9	用量超过窗口限额的此比例时发出一次警告。
AUTORIA_LOG_LEVEL	INFO	软件包日志级别。

API 密钥保存在 SecretStr 中，绝不会写入日志。

运行

# stdio (default) — how MCP clients launch it
autoria-mcp

# streamable-HTTP
autoria-mcp --transport http --host 127.0.0.1 --port 8000
# or
AUTORIA_TRANSPORT=http autoria-mcp

请参阅 examples/，其中包含可直接粘贴使用的 MCP 客户端配置（Claude Desktop 和通用 stdio 客户端）。

配额说明

AUTO.RIA 免费套餐按所有 RIA Web 服务共用的每个 API 密钥计量，且限额较严格：

• 约 1000 次请求／月
• 30 次请求／小时（滚动计量）；超过任一限额都会返回 429 OVER_RATE_LIMIT， 并暂时封禁该密钥。

响应中没有 X-RateLimit-* 标头，因此客户端会在本地跟踪用量（第 3 阶段）。请将每次实时调用都视为在消耗稀缺配额：字典端点会被积极缓存，搜索／统计响应也不应在没有必要时重复获取。

工具目录

精选工具——可输入自然语言（名称、范围），并自动解析为 ID：

工具	描述
search_used_cars	按品牌／车型／地区／年份／价格／发动机排量／功率／代际等条件搜索；返回匹配的 count 和广告 ID。
get_car_details	获取单个广告 ID 的简要详情：价格、年份、里程、结构化的发动机排量／功率、带标签的车身／燃料／变速箱信息，以及 condition／risk／verification／seller／photo 来源信息、展示的 VIN、屏蔽后的电话号码和 URL。
get_car_details_batch	一次调用获取最多 50 个广告 ID 的详情（去重；失效 ID 返回精简条目）。
lookup_brands	列出乘用车品牌，或将一个品牌名称解析为其 ID。
lookup_models	列出某品牌的车型，或将一个车型名称解析为其 ID。
lookup_regions	列出地区（州），或将一个地区名称解析为其 ID。
lookup_cities	列出某地区的城市，或将一个城市名称解析为其 ID。

付费工具（需要 AUTORIA_USER_ID；否则会立即失败并返回明确错误）：

工具	描述
get_average_price	AI 平均价格及可比列表（按参数或 omni_id 查询）。
get_average_price_over_periods	月度平均价格时间序列。
get_params_by_vin	将 VIN／车牌／广告 ID 解码为汽车参数标签。

精简镜像（原始直通，缓存 7 天）：list_categories、 list_all_models、list_models_grouped、list_generations、list_modifications、 list_modifications_by_body、list_equipment、list_options、list_options_v2、 list_colors、list_countries、list_drive_types、list_fuel_types、 list_gearboxes、list_body_styles、list_body_styles_grouped、 list_all_body_styles、list_bodies_by_generation，以及 raw_search（原始 V1 搜索；默认返回精简的 {count, ids}，设置 verbose=True 可获取完整负载）。

资源：autoria://dict/{categories,colors,countries,fuel-types,gearboxes, body-styles,states}，以及模板化资源 autoria://dict/models/{categoryId}/{markId}。

健康检查：ping——不消耗配额的存活状态／诊断检查。

署名

AUTO.RIA 的 API 条款要求：凡展示来自该 API 的数据，都必须提供指向 auto.ria.com 的可见链接。get_car_details 和付费端点都包含每条列表的规范深层链接（url）；请确保在面向最终用户展示列表的界面中保留该链接。（search_used_cars 仅返回 ID 和计数——公共 API 未指定整组搜索结果的链接，因此不会虚构此类链接。）

已知限制

以下是有意设定的范围／行为选择，在依赖这些功能前值得了解：

• 每次搜索仅支持一个品牌／车型。 search_used_cars 尚未支持多品牌或多车型搜索。若要跨多个品牌进行 OR 式查询，请改用 raw_search 并自行传入原始 V1 参数。
• 搜索返回 ID，而非完整车源。 search_used_cars 会返回广告 ID 和 count。使用 get_car_details 获取单条车源详情（若要查询整页 ID，请使用 get_car_details_batch）——每次查询都会消耗配额，因此只查询所需内容。
• 搜索仅支持 V1，且会静默忽略未知参数——这是个真正的陷阱。底层的 /auto/search 端点不会验证筛选键：拼写错误或不受支持的参数会被丢弃，搜索范围会悄悄扩大到整个网站，而不会报错。精选工具会将名称解析为正确的 V1 ID，以避免此问题，但 raw_search 会原样传递你的参数。
• 付费 POST 错误会以 HTTP 200 返回。 付费端点会在响应正文中返回错误（noticeType: "error"），但状态码为 200；付费工具会检测到这些错误并将其作为工具错误显示。
• get_average_price_over_periods 仅接受 period ∈ {30, 90, 180, 365}。

开发

uv sync                     # create venv + install deps (incl. dev group)
uv run ruff check .         # lint
uv run ruff format --check .  # format check
uv run mypy                 # strict type check (src + tests)
uv run pytest               # tests (no network)
pre-commit install          # enable git hooks

OpenAPI 3.1 描述位于 openapi/autoria-used-cars.yaml。

路线图

1. ✅ 阶段 1 — OpenAPI 规范、经过实时验证的 API 信息。
2. ✅ 阶段 2 — 仓库脚手架、工具链、CI、打包、可运行的服务。
3. ✅ 阶段 3 — 类型化异步客户端、TTL 字典缓存、名称→ID 解析、录制夹具测试（不消耗实时配额）。
4. ✅ 阶段 4 — 精选工具、付费工具、轻量工具、字典 MCP 资源。
5. ✅ 阶段 5 — 文档、示例、首个 PyPI 版本发布（0.1.0）。

1.0 之后的待办事项（尚未安排）：原生多品牌／多车型搜索；各端点独立的缓存 TTL；跨进程配额锁（当前配额统计按进程进行，仅发出警告）；供基于 Node 的 MCP 客户端使用的 npx 垫片。

许可证

MIT。这是一个非官方项目，与 RIA.com / AUTO.RIA 无关联，也未获其认可。