AUTO.RIA Used Cars

autoria-mcp

ＭＣＰ サーバーです。AUTO.RIA 中古車 REST API（auto.ria.com、developers.ria.com 経由）を AI エージェントに公開し、認可された API を通じてウクライナの中古車市場へプログラムからエージェントに適した方法でアクセスできます。スクレイピングは不要です。

ツール一式が利用可能です。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 を実行するための小さなツールです）。ターミナルアプリを開き、以下を貼り付けて 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 の絶対パスを確認します。 デスクトップアプリからはターミナルの設定を参照できないため、絶対パスが必要です。ターミナルで次を実行します。

which uvx

表示された内容をコピーします。通常は /opt/homebrew/bin/uvx（Apple Silicon 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" を追加します。 ない場合は、ブロック全体を貼り付けます。2 つのプレースホルダー値を置き換えてください。

{
  "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 検索）を使う場合は、env に "AUTORIA_USER_ID": "..." を追加します。その際、API キーの行の後ろにカンマを付けます。例： "env": { "AUTORIA_API_KEY": "...", "AUTORIA_USER_ID": "..." }。

ファイルを保存します。

6. Claude を完全に終了して、再度開きます。 Cmd + Q を押します（ウィンドウを閉じるだけでは不十分です）。その後、Claude を再度開きます。最初の起動時はツールのダウンロードに数秒かかりますが、次回以降はすぐに起動します。

7. 試してみましょう。 Claude に次のように尋ねます。 "autoria を使って、キーウで中古の BMW 3 シリーズを探し、価格付きでいくつか表示してください。"

利用上限について： 無料の AUTO.RIA キーでは、1 時間あたり約 30 回、月あたり 1000 回リクエストできます。そのため、範囲の広い質問ではなく、対象を絞った質問をしてください。

再起動後に autoria が表示されない場合は、通常、ログファイルに原因が記録されています。

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

よくある対処方法：uvx の絶対パスを使う（手順 3）ことと、Cmd + Q で Claude を完全に終了することを確認してください。

Windows

Windows での手順は同じですが、macOS とはコマンドが異なり、Windows 固有の注意点もいくつかあります。

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. https://developers.ria.com で無料の AUTO.RIA API キーを取得します。すぐ使えるようにしておいてください。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 ではなく where.exe を使用してください。 単独の where は Where-Object のエイリアスであり、実行ファイルを検索できません。

セットアップに失敗する最大の原因です。 フルパスではなく uvx だけを指定すると、アプリは見つからないと表示します。必ず手順 3 のフルパスを貼り付けてください。

4. Claude Desktop の設定ファイルを開きます。アプリ内のボタンを使用してください。 Claude アプリで、Settings → Developer → Edit Config を選択します。インストール環境に合った 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 サーバーの読み込みが通知なく失敗します。Edit Config ボタンを使えば必ず正しいファイルが開きます。

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 アイコンを右クリックし、Quit を選択します。ウィンドウを閉じるだけでは不十分です。その後、Claude を再び開きます。ツールをダウンロードするため、初回の起動には数秒かかりますが、それ以降はすぐに起動します。

7. 試してみましょう。 Claude に次のように尋ねてみてください。 「autoria を使って、キーウで中古の BMW 3 シリーズを探し、価格付きで何台か表示してください。」

同じ制限事項と、よくある問題への対処法が適用されます。uvx.exe のフルパス（手順 3）を使用し、アプリ内のボタン（手順 4）から設定を編集して、トレイから完全に終了してください（手順 6）。ログは %APPDATA%\Claude\logs\mcp-server-autoria.log にあります。

設定

すべての設定は、環境変数（プレフィックスは AUTORIA_）またはローカルの .env ファイルから読み込まれます。.env.example を .env にコピーし、キーを設定してください。

変数	デフォルト	説明
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	1 回のバックオフ待機における最大時間（秒）です。
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

すぐに貼り付けて使える MCP クライアント設定については、examples/ を参照してください（Claude Desktop および汎用の stdio クライアント）。

クォータに関するガイダンス

AUTO.RIA の無料プランでは、すべての RIA ウェブサービスで API キーごとにリクエスト数が計測され、 上限は厳しく設定されています。

• 約 1000 リクエスト／月
• 30 リクエスト／時間（ローリング方式）。いずれかの上限を超えると 429 OVER_RATE_LIMIT が返され、 キーが一時的にブロックされます。

X-RateLimit-* レスポンスヘッダーは存在しないため、クライアントが使用量をローカルで追跡します （フェーズ 3）。ライブ呼び出しはすべて、貴重なクォータを消費するものとして扱ってください。辞書 エンドポイントは積極的にキャッシュされます。検索／統計レスポンスは、必要のない再取得を避けてください。

ツールカタログ

厳選ツール — 自然な入力（名称、範囲）を受け取り、IDに解決します。

Tool	Description
search_used_cars	ブランド／モデル／地域／年式／価格／排気量／出力／世代などで検索し、一致したcountと広告IDを返します。
get_car_details	1件の広告IDについて、価格、年式、走行距離、構造化された排気量／出力、ラベル付きのボディ／燃料／ギアボックスに加え、condition／risk／verification／seller／photoの出所情報、表示されている場合はVIN、マスキングされた電話番号、URLを含む簡潔な詳細を返します。
get_car_details_batch	1回の呼び出しで最大50件の広告IDの詳細を返します（重複は除去され、無効なIDは情報の少ないエントリーを返します）。
lookup_brands	乗用車ブランドの一覧を返すか、ブランド名をIDに解決します。
lookup_models	ブランドのモデル一覧を返すか、モデル名をIDに解決します。
lookup_regions	地域（州）の一覧を返すか、地域名をIDに解決します。
lookup_cities	地域の都市一覧を返すか、都市名をIDに解決します。

有料ツール（AUTORIA_USER_IDが必要です。設定されていない場合は、明確なエラーを返して即座に失敗します）。

Tool	Description
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と件数のみです。Public APIには検索結果全体へのリンクが定義されていないため、そのようなリンクは作成していません。）

既知の制限事項

利用する前に把握しておくべき、意図的なスコープおよび動作上の選択事項です。

• 検索ごとにブランド／モデルは1つです。 複数ブランドまたは複数モデルの検索は、まだ 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で返されます。 有料エンドポイントは、ステータス200で本文にエラー（noticeType: "error"）を返します。有料ツールはこれを検出し、ツールエラーとして通知します。
• 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 とは提携しておらず、承認も受けていません。