tsb-kasko-mcp — TSB Kasko Değer Listesi用MCPサーバーとCLI

Türkiye Sigorta Birliği（TSB）が公開しているKasko Değer Listesi（カスコ価格リスト）を照会する オープンソースのMCPサーバー、コマンドラインツール、Pythonクライアントです。 Claude、ChatGPT、Gemini、Cursor内から「2025年型Audi A3のカスコ価格はいくらですか」と尋ねたり、 ターミナルから tsb-kasko lookup 2025 "audi a3" と入力したり、 自分のPythonプロジェクトでライブラリとして使用できます。

カスコ価格リストは、トルコで販売されるすべてのカスコ保険の保険料を決定する基準価格です。 また、全損（完全損害）や盗難の場合に支払われる金額の根拠でもあります。 このプロジェクトは、TSBのウェブサイトのバックグラウンドで使用されている、 認証不要のエンドポイントを型付けされたクライアントに変換します。

パッケージをインストールすると、2つのコマンドが同時に利用可能になります。別途CLIパッケージをインストールする必要はありません。

目次

• このツールの目的

• インストール

• MCPのセットアップ

• MCPツール

• コマンドラインの使い方

• Pythonライブラリとして

• Docker

• 設定

• 使用するTSBエンドポイント

• プロジェクト構造

• 開発

• よくある質問

• 免責事項

Related MCP server: RACV Insurance MCP Server

このツールの目的

• AIアシスタントからのカスコ価格照会。 Claude、ChatGPT、Gemini内で自然言語で質問すると、モデルがツールを呼び出し、最新の価格を返します。

• ターミナルからの照会。 tsb-kasko lookup 2025 "audi a3 sportback" コマンドで、テーブル、JSON、CSVを直接出力します。

• 保険証券の車両コード。 結果には、保険会社が尋ねる ブランドコード - モデルコード のペアも含まれています（例：9-1616）。

• 過去のリスト。 TSBは毎月リストを再公開します。過去の月のExcelファイルをダウンロードしたり、その中を検索したりできます。

• Pythonライブラリ。 自分のプロジェクトで TsbKaskoClient クラスを直接使用できます。

インストール

前提条件： uv。Pythonも自動でインストールされます。

インストールせずに試す場合：

uvx --from git+https://github.com/hmtkyn/tsb-kasko-mcp tsb-kasko lookup 2025 "audi a3 sportback"

恒久的なインストール：

uv tool install git+https://github.com/hmtkyn/tsb-kasko-mcp

またはpipで：

pip install git+https://github.com/hmtkyn/tsb-kasko-mcp

パッケージはまだPyPIで公開されていません。公開され次第、uv tool install tsb-kasko-mcp や pip install tsb-kasko-mcp も使えるようになります。公開ワークフローはリポジトリに用意されています。

リポジトリからの開発インストールについては、開発のセクションを参照してください。

MCPのセットアップ

サーバーは stdio とストリーミング可能なHTTPトランスポートの両方をサポートしているため、 デスクトップクライアントとホスト型コネクタの両方で動作します。

Claude Code

claude mcp add tsb-kasko -- uvx --from git+https://github.com/hmtkyn/tsb-kasko-mcp tsb-kasko-mcp

Claude Desktop

claude_desktop_config.json ファイルに追加：

{
  "mcpServers": {
    "tsb-kasko": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/hmtkyn/tsb-kasko-mcp", "tsb-kasko-mcp"]
    }
  }
}

Cursor / VS Code

.cursor/mcp.json またはワークスペースの .vscode/mcp.json ファイルに同じ mcpServers ブロックを追加します。

Gemini CLI

~/.gemini/settings.json ファイルに追加：

{
  "mcpServers": {
    "tsb-kasko": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/hmtkyn/tsb-kasko-mcp", "tsb-kasko-mcp"]
    }
  }
}

ChatGPT およびその他のリモートクライアント

ChatGPTコネクタはHTTP経由でサーバーにアクセスします。サーバーをHTTPモードで実行します：

TSB_KASKO_TRANSPORT=http TSB_KASKO_HOST=0.0.0.0 TSB_KASKO_PORT=8000 tsb-kasko-mcp

または任意のASGIサーバーで：

uvicorn tsb_kasko.asgi:app --host 0.0.0.0 --port 8000

エンドポイントはデフォルトで http://sunucu:8000/mcp で公開されます。最も簡単な方法はDockerのセクションを参照してください。

MCPツール

kasko_download_archive を除くすべてのツールは readOnlyHint でマークされています。つまり、クライアントは承認を求めずにそれらを呼び出すことができます。

コマンドラインの使い方

# Kapsanan model yılları
tsb-kasko years

# Bir model yılındaki markalar
tsb-kasko brands 2025

# Bir markanın tipleri
tsb-kasko models 2025 audi

# Serbest metinle sorgulama
tsb-kasko lookup 2025 "audi a3 sportback s line"

# Markayı sabitleyerek hızlandırma
tsb-kasko lookup 2025 "corolla hybrid" --brand toyota --limit 10

# JSON veya CSV çıktısı
tsb-kasko lookup 2025 "audi a3" --format json
tsb-kasko brands 2025 --format csv > markalar.csv

# Arşiv
tsb-kasko archive months
tsb-kasko archive file 2025 2
tsb-kasko archive search 2025 2 --query "sahin" --limit 20
tsb-kasko archive download 2025 2 --output ~/Downloads

# Önbellek
tsb-kasko cache path
tsb-kasko cache clear

# MCP sunucusunu CLI üzerinden çalıştırma
tsb-kasko serve --transport http --port 8000

出力例：

                      audi a3 sportback in 2025
┏━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┓
┃ Vehicle Code ┃ Brand ┃ Model                               ┃ Kasko Value    ┃
┡━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━┩
│ 9-1616       │ AUDI  │ A3 SPORTBACK 35 TFSI 150 S LINE ... │ 3.695.439,00 TL│
└──────────────┴───────┴─────────────────────────────────────┴────────────────┘

Pythonライブラリとして

import asyncio

from tsb_kasko import TsbKaskoClient


async def main() -> None:
    async with TsbKaskoClient() as client:
        for value in await client.lookup(2025, "audi a3 sportback"):
            print(value.vehicle_code, value.model_name, value.amount)


asyncio.run(main())

Docker

コンテナはMCPサーバーをHTTPトランスポートで公開します。マルチステージビルドを使用し、非rootユーザーで実行され、ファイルシステムは読み取り専用です。

docker compose up --build
# -> http://127.0.0.1:8000/mcp

イメージをビルドしてCLIを実行するだけの場合：

docker build -f .docker/python/Dockerfile -t tsb-kasko-mcp .
docker run --rm --entrypoint tsb-kasko tsb-kasko-mcp lookup 2025 "audi a3"

Pythonのバージョンはイメージ内で ARG PYTHON_VERSION に固定されており、リポジトリの .python-version と同じバージョンを使用します。

設定

すべての設定は環境変数で上書きできます。

使用するTSBエンドポイント

TSBはAPI契約を公開していません。以下のエンドポイントは、サイトのフロントエンドが使用している、認証やクッキーを必要としないものです。 すべて src/tsb_kasko/endpoints.py で一箇所に定義されています。

2つの詳細が注目に値します：

1. ブランドリストの VehicleBrandCode フィールドは常に 0 になります。保険証券に記載されている実際のブランドコードは、GetInsuranceDatas の応答でのみ埋まっています。

2. GetMonthList の Id フィールドは暦月ではありません。1月は 2、10月は 1 のIDを持ちます。そのため、クライアントは月IDを計算せず、ライブリストから解決します。

プロジェクト構造

3つのインターフェースはすべて、同じコアの上に載った薄いラッパーです。そのため、すべてが1つのリポジトリに存在します：TSBがエンドポイントをリネームした場合、修正は1つのファイルで行われ、3つの別々のバージョンを同期する必要はありません。

src/tsb_kasko/
├── client.py      # çekirdek: HTTP, yeniden deneme, önbellek
├── endpoints.py   # TSB uçlarının tek tanım yeri
├── models.py      # Pydantic modelleri
├── parsing.py     # zarf açma, Türkçe sayı ve metin normalleştirme
├── archive.py     # aylık Excel listelerinin okuyucusu
├── server.py      # kabuk 1: FastMCP sunucusu
├── cli.py         # kabuk 2: Typer komut satırı
└── asgi.py        # HTTP taşıması için ASGI uygulaması

同じ構成は github/github-mcp-server、microsoft/playwright-mcp、grafana/mcp-grafana プロジェクトでも使用されています：共通コアの上に複数のエントリポイント。

開発

git clone https://github.com/hmtkyn/tsb-kasko-mcp.git
cd tsb-kasko-mcp
uv sync --all-extras --all-groups
uv run pre-commit install

uv run pytest                                  # 146 test, kayıtlı gerçek yanıtlarla
uv run pytest --cov --cov-report=term-missing  # kapsam raporu
uv run ruff check .                            # lint
uv run ruff format .                           # biçimlendirme
uv run mypy src/tsb_kasko                      # strict tip denetimi
uv run pre-commit run --all-files              # CI'ın yaptığının tamamı

テストはTSBから取得した実際の応答の完全なコピーを使用するため、契約が変更された場合にテストが失敗します。ネットワークを使用するテストはありません。

Windows、macOS、Linuxで同じ結果

このリポジトリは、3つのOSすべてで同じ動作をするように設定されています：

• .python-version はPythonバージョンを3.14に固定します。uv が必要に応じてダウンロードします。パッケージがサポートする範囲は >=3.11 で、CIは4つのバージョンをすべてテストします。

• .gitattributes はすべてのテキストファイルをリポジトリ内でLFで保存します。Windowsで core.autocrlf が有効でも、リポジトリにCRLFは入りません。CIのステップでこれをさらにチェックします。

• .editorconfig はインデント、エンコーディング、改行をエディタに依存せずに固定します。

• .devcontainer/ を使用すると、何もインストールせずにコンテナ内で開発できます。

詳細は CONTRIBUTING.md を参照してください。

よくある質問

カスコ価格とは何ですか？どのように決定されますか？ TSBが毎月発行する、ブランドとタイプに基づく基準車両価格です。 保険会社はこの価格に基づいて保険料と損害賠償を計算します。

自分の車のカスコ価格を調べるには？ tsb-kasko lookup <model_yılı> "<marka ve tip>" コマンドを実行するか、MCPサーバーを設定してアシスタントに尋ねてください。公式の情報源は常に tsb.org.tr です。

保険証券の車両コードとは何ですか？ 保険会社が尋ねる ブランドコード - モデルコード のペアで、例：9-1616。 結果の vehicle_code フィールドに返されます。

カバーされるモデル年は？ 2012年以降。最新のリストは tsb-kasko years で確認できます。

過去の月のリストにアクセスできますか？ はい。tsb-kasko archive search 2025 2 --query "sahin" で過去の月のExcelファイルを検索でき、archive download でファイル自体をダウンロードできます。

このプロジェクトは公式ですか？ いいえ。以下の免責事項を参照してください。

免責事項

このプロジェクトはTSBとは関係がなく、TSBによってサポートされていません。データはTSBの公開ページから取得されます。TSB自身の声明によれば、これらの価格を取引に使用した結果についてTSBは責任を負いません。 公式の情報源は常に tsb.org.tr です。

エンドポイントはTSBによって文書化されていないため、予告なく変更される可能性があります。その場合は、src/tsb_kasko/endpoints.py ファイルを更新するだけで十分です。

コントリビューションとライセンス

• コントリビューションガイド：CONTRIBUTING.md

• 行動規範：CODE_OF_CONDUCT.md

• セキュリティポリシー：SECURITY.md

• 変更履歴：CHANGELOG.md

MITライセンスで公開されています。トルコ語情報の翻訳：docs/lisans.md.