Skip to main content
Glama
tsb-kasko-mcp

tsb-kasko-mcp

by the-up

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プロジェクトでライブラリとして使用できます。

CI Python MCP Lisans: MIT Test kapsamı

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

インターフェース

実行方法

対象

MCPサーバー

tsb-kasko-mcp

Claude, ChatGPT, Gemini, Cursor

コマンドライン

tsb-kasko lookup 2025 "audi a3"

ターミナル、スクリプト、CI

Pythonクライアント

from tsb_kasko import TsbKaskoClient

自作アプリケーション

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

目次

Related MCP server: DPVAT: Emissão de Guia

このツールの目的

  • 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_lookup

フリーテキストから車両を検索し、各マッチのカスコ価格を返します。これがメインツールです。

kasko_list_model_years

リストがカバーするモデル年を返します。対象は2012年以降です。

kasko_list_brands

特定のモデル年のブランドを一覧表示します。

kasko_list_models

特定のブランドのそのモデル年におけるタイプを一覧表示します。

kasko_get_value

モデルIDがわかっている単一の車両の価格を読み取ります。

kasko_archive_file

特定の月の公開済みExcelファイルを解析します。

kasko_search_archive

過去の月のリスト内を検索します。

kasko_download_archive

特定の月のExcelファイルをディスクにダウンロードします。

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_KASKO_BASE_URL

https://www.tsb.org.tr

TSBアプリケーションのルートアドレス。

TSB_KASKO_TIMEOUT

30

リクエストごとのタイムアウト(秒)。

TSB_KASKO_MAX_RETRIES

3

一時的なエラー時の再試行回数。

TSB_KASKO_CACHE

1

0 にするとキャッシュが完全に無効になります。

TSB_KASKO_CACHE_TTL

21600

ブランドとモデルリストのキャッシュ有効期限(秒)。

TSB_KASKO_CACHE_DIR

~/.cache/tsb-kasko

キャッシュディレクトリ。

TSB_KASKO_TRANSPORT

stdio

MCPトランスポート:stdio、http、sse。

TSB_KASKO_HOST

127.0.0.1

HTTPトランスポートのリスニングアドレス。

TSB_KASKO_PORT

8000

HTTPトランスポートのポート。

TSB_KASKO_MCP_PATH

/mcp

ASGIアプリケーションのエンドポイントパス。

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

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

エンドポイント

パラメータ

戻り値

GET /InsuranceData/GetVehicleYearList

なし

カバーされるモデル年

GET /InsuranceData/GetVehicleBrandList

VehicleYear

ブランド

GET /InsuranceData/GetVehicleModelList

vehicleYear, VehicleBrandId

タイプ

GET /InsuranceData/GetInsuranceDatas

VehicleYear, VehicleModelId

カスコ価格と車両コード

GET /InsuranceData/GetMonthList

なし

アーカイブ月

GET /InsuranceData/GetInsuranceDataArchiveFile

Year, MonthId

月次Excelファイルのパス

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 ファイルを更新するだけで十分です。

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

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

Available Tools

8 tools
kasko_archive_fileA
Read-only

Resolve the monthly kasko list spreadsheet published by TSB.

TSB republishes the full list every month and keeps the past editions online. Use this to cite or hand the user the exact file for a given month, or to compare a current value against an older one.

Inputs: year (required), month (required). Returns: object

kasko_download_archiveA

Download a monthly kasko list spreadsheet to disk.

Use this when the user wants the whole list as a file rather than a few rows. Prefer kasko_search_archive when they only need specific vehicles.

Inputs: year (required), month (required), destination. Returns: object

kasko_get_valueA
Read-only

Read the kasko value of one exact model by its identifier.

Use this after the user picks a specific row from kasko_list_models. When the vehicle is only described in words, use kasko_lookup instead.

Inputs: model_id (required), model_year (required). Returns: object

kasko_list_brandsA
Read-only

List the vehicle brands available for a model year.

Brand availability differs per model year, so the year is required. The returned brand_id is the identifier kasko_list_models expects; it is not the brand code printed on policies.

Inputs: model_year (required). Returns: object

kasko_list_modelsA
Read-only

List the models of one brand in a model year.

Model names carry trim, engine and gearbox information, which is what makes two rows of the same nameplate differ in value. The returned model_id is the identifier kasko_get_value expects.

Inputs: brand (required), model_year (required). Returns: object

kasko_list_model_yearsA
Read-only

List the vehicle model years covered by the TSB kasko value list.

Call this when the user gives no model year, or to check whether a year is covered before querying it. Coverage starts at 2012.

Returns: A mapping with the covered model years in descending order.

Inputs: no named parameters. Returns: object

kasko_lookupA
Read-only

Look up the kasko value of a vehicle from a free text description.

This is the primary tool. It resolves the description to matching models and returns the value of each, so no identifier lookup is needed first. Every result carries vehicle_code, the brand and model code pair printed on policies, which is the value an insurer will ask for.

When several trims match, present them to the user rather than guessing: the spread between trims of the same nameplate is often large.

Inputs: query (required), model_year (required), brand, limit. Returns: object

kasko_search_archiveA
Read-only

Search inside a past monthly kasko list.

Answers historical questions the live endpoints cannot, such as what a vehicle was valued at earlier in the year. The spreadsheet is downloaded and filtered server side, so keep the query specific.

Inputs: year (required), month (required), limit, query. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool has a distinct purpose: browsing hierarchy (years, brands, models), direct value lookup (free-text vs exact ID), and archive handling (resolve, search, download). No two tools overlap enough to cause confusion, and the descriptions clearly differentiate kasko_lookup from kasko_get_value.

    Naming Consistency4/5

    Most tools follow the kasko_<verb>_<object> pattern (list_brands, get_value, search_archive). Minor deviations: kasko_lookup lacks an object, and kasko_archive_file is noun-like rather than verb-led. Overall the convention is consistent and readable.

    Tool Count5/5

    With 8 tools, the set is well-scoped for a kasko lookup service. Three tools cover hierarchical browsing, two cover value retrieval, and three cover archive operations. No tool feels redundant or missing.

    Completeness5/5

    The surface covers the full user journey: discover coverage years, browse brands/models, get current value by text or exact ID, and access historical data via archive tools. No critical operations are missing for a read-only reference service.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      MCP server that unifies official Turkish open data sources into a single interface, letting AI agents query and compare normalized indicators like population, inflation, and GDP through natural language.
      10
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Read-only MCP server for querying DPVAT (Brazilian insurance) guide issuance information from an official source. It provides a single tool that allows users to consult DPVAT guide data via natural language in any MCP-compatible client.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables product search, store price comparison, basket comparison, and price history review using Market Fiyatı data through a stdio MCP server.
      15
      299 npm
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents and MCP clients to compare Iranian insurers, ratings, and live prices for travel, third-party, car body, motorcycle, fire, and supplementary health insurance across BimeBazar and Azki, with Persian-aware, read-only access and no API key.
      18
      97 PyPI
      1
      PolyForm Noncommercial 1.0.0