autoria-mcp

An MCP server that exposes the AUTO.RIA used-cars REST API (auto.ria.com, via developers.ria.com) to AI agents — programmatic, agent-friendly access to the Ukrainian used-car market through the sanctioned API, no scraping.

The full tool surface is live — 30 tools, 7 dictionary resources, and 1 templated resource: curated search/lookup tools (single and batch listing details), paid statistics tools, thin endpoint mirrors, and browsable dictionary resources, all backed by tiered caching and a typed async client.

Features

• Curated, high-level tools that take human-friendly inputs (brand, model, region, year/price ranges) and resolve them to AUTO.RIA's numeric IDs for you.
• Paid statistics tools (AI average price, price-over-time, VIN decode) that fail fast with a clear error when AUTORIA_USER_ID is unset — no wasted quota.
• Thin endpoint mirrors for the long-tail dictionary/lookup endpoints.
• Dictionary resources — browse categories, colours, regions, etc. as addressable autoria://dict/... documents.
• Aggressive, tiered caching: large slow-changing dictionaries are cached on disk for 7 days (name→ID resolution costs no quota after the first fetch), while volatile search/statistics responses are cached briefly, in memory only.
• stdio and streamable-HTTP transports.

Install

Requires Python 3.11+. The package is distributed on PyPI; run it without a manual install using uvx:

uvx autoria-mcp

Or install into a tool environment with pipx / uv tool:

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

Quickstart: Claude Desktop (no coding required)

Want to use AUTO.RIA from the Claude desktop app? Follow these steps — no programming needed, just some copy-and-paste. Pick your platform: macOS · Windows.

macOS

1. Install uv (the small tool that runs autoria-mcp for you). Open the Terminal app and paste this, then press Enter:

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

(Full instructions: https://docs.astral.sh/uv/getting-started/installation/.)

2. Get a free AUTO.RIA API key at https://developers.ria.com. Keep it handy. A user_id is optional — you only need it for the paid price-statistics tools.

3. Find the full path to uvx. The desktop app can't see your Terminal's settings, so it needs the full path. In Terminal, run:

which uvx

Copy what it prints — usually /opt/homebrew/bin/uvx (Apple-Silicon Mac) or /usr/local/bin/uvx (Intel Mac).

This is the #1 reason setup fails. If you use just uvx instead of the full path, the app says it can't find it. Always paste the full path from which uvx.

4. Open Claude Desktop's config file. In the Claude app: Settings → Developer → Edit Config. This opens a file called claude_desktop_config.json (on macOS it lives at ~/Library/Application Support/Claude/claude_desktop_config.json).

5. Add the autoria server. Paste the block below. If the file already has a "mcpServers" section, add "autoria" inside it next to your other servers; otherwise paste the whole thing. Replace the two placeholder values:

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

• command → the full path from step 3.
• AUTORIA_API_KEY → your key from step 2.
• For the paid tools (average price, VIN lookup), add "AUTORIA_USER_ID": "..." to env — put a comma after the API-key line when you do, e.g. "env": { "AUTORIA_API_KEY": "...", "AUTORIA_USER_ID": "..." }.

Save the file.

6. Fully quit and reopen Claude. Press Cmd + Q (just closing the window isn't enough), then open Claude again. The first start takes a few seconds while it downloads the tool; after that it's instant.

7. Try it. Ask Claude something like: "Use autoria to find used BMW 3 Series cars in Kyiv and show me a few with prices."

Heads-up on limits: the free AUTO.RIA key allows roughly 30 requests/hour and 1000/month — so ask focused questions rather than broad ones.

If autoria doesn't show up after restarting, the log file usually says why:

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

Most common fixes: use the full uvx path (step 3), and make sure you fully quit Claude with Cmd + Q.

Windows

The same flow on Windows — the commands and a couple of Windows-only gotchas differ from macOS.

1. Install uv (it ships the uvx command that runs autoria-mcp). Open PowerShell and run either:

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

or, if you use winget:

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

Then open a new terminal window so the updated PATH takes effect. (Full instructions: https://docs.astral.sh/uv/getting-started/installation/.)

2. Get a free AUTO.RIA API key at https://developers.ria.com. Keep it handy. A user_id is optional — you only need it for the paid price-statistics tools.

3. Find the full path to uvx.exe. The desktop app can't see your terminal's PATH, so it needs the full path. In PowerShell, run:

Get-Command uvx | Select-Object -ExpandProperty Source

or in Command Prompt (cmd):

where.exe uvx

Copy what it prints — usually C:\Users\<you>\.local\bin\uvx.exe.

In PowerShell, use where.exe, not where. Plain where is an alias for Where-Object and won't find the executable.

This is the #1 reason setup fails. If you use just uvx instead of the full path, the app says it can't find it. Always paste the full path from step 3.

4. Open Claude Desktop's config file — use the in-app button. In the Claude app: Settings → Developer → Edit Config. This opens the correct claude_desktop_config.json for your install.

Don't hand-edit the %APPDATA% file. The documented location is %APPDATA%\Claude\claude_desktop_config.json (= C:\Users\<you>\AppData\Roaming\Claude\claude_desktop_config.json), but the Microsoft Store / MSIX build of Claude virtualizes that folder — it actually reads from %LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json. Editing the plain %APPDATA% copy then makes your MCP servers silently fail to load. The Edit Config button always opens the right file — use it.

5. Add the autoria server. Paste the block below. If the file already has a "mcpServers" section, add "autoria" inside it next to your other servers; otherwise paste the whole thing. On Windows, backslashes in JSON must be doubled (\\) — or use forward slashes (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 → the full path from step 3, with doubled backslashes.
• AUTORIA_API_KEY → your key from step 2.
• For the paid tools (average price, VIN lookup), add "AUTORIA_USER_ID": "..." to env — put a comma after the API-key line when you do, e.g. "env": { "AUTORIA_API_KEY": "...", "AUTORIA_USER_ID": "..." }.

Save the file. A ready-to-edit copy is at examples/claude_desktop_config_windows.json.

Prefer not to keep your key in the config? Omit the env block and instead put AUTORIA_API_KEY in a .env file in the working directory, or set it as a Windows user/system environment variable.

6. Fully restart Claude. Right-click the Claude icon in the system tray (near the clock) and choose Quit — just closing the window isn't enough — then open Claude again. The first start takes a few seconds while it downloads the tool; after that it's instant.

7. Try it. Ask Claude something like: "Use autoria to find used BMW 3 Series cars in Kyiv and show me a few with prices."

The same limits and most-common fixes apply: use the full uvx.exe path (step 3), edit the config via the in-app button (step 4), and fully quit from the tray (step 6). Logs are at %APPDATA%\Claude\logs\mcp-server-autoria.log.

Configuration

All settings are read from environment variables (prefix AUTORIA_) or a local .env file. Copy .env.example to .env and fill in your key.