Skip to main content
Glama
tsb-kasko-mcp

tsb-kasko-mcp

by the-up

tsb-kasko-mcp — MCP-Server und CLI für die TSB Kasko Değer Listesi

Ein Open-Source MCP-Server, Kommandozeilentool und Python-Client zum Abfragen der von der Türkiye Sigorta Birliği (TSB) veröffentlichten Kasko Değer Listesi. Claude, ChatGPT, Gemini und Cursor können fragen: „Wie hoch ist der Kaskowert eines Audi A3 Modell 2025?“; im Terminal tsb-kasko lookup 2025 "audi a3" eingeben oder es als Bibliothek in Ihrem eigenen Python-Projekt verwenden.

CI Python MCP Lizenz: MIT Testabdeckung

Die Kasko-Wertliste ist der Referenzbetrag, nach dem jede in der Türkei verkaufte Kaskoversicherungspolice bepreist wird. Sie ist auch die Grundlage für die im Falle eines Totalschadens (pert) oder Diebstahls zu zahlende Summe. Dieses Projekt wandelt die von der TSB-Website im Hintergrund verwendeten, nicht authentifizierungspflichtigen Endpunkte in einen typisierten Client um.

Schnittstelle

Wie ausführen

Für wen

MCP-Server

tsb-kasko-mcp

Claude, ChatGPT, Gemini, Cursor

Kommandozeile

tsb-kasko lookup 2025 "audi a3"

Terminal, Skript, CI

Python-Client

from tsb_kasko import TsbKaskoClient

Ihre eigene Anwendung

Bei der Installation des Pakets werden zwei Befehle bereitgestellt; Sie müssen kein separates CLI-Paket installieren.

Inhaltsverzeichnis

Related MCP server: DPVAT: Emissão de Guia

Wozu dient es?

  • Kaskowertabfrage über KI-Assistenten. Sie fragen in natürlicher Sprache über Claude, ChatGPT und Gemini, das Modell ruft das Werkzeug auf und gibt den aktuellen Wert zurück.

  • Abfrage über das Terminal. Der Befehl tsb-kasko lookup 2025 "audi a3 sportback" gibt die Tabelle, JSON oder CSV direkt aus.

  • Fahrzeugcode in der Police. Die Ergebnisse enthalten auch das vom Versicherer angeforderte Paar Markencode - Modellcode, z.B. 9-1616.

  • Historische Listen. TSB veröffentlicht die Liste jeden Monat neu. Sie können die Excel-Datei vergangener Monate herunterladen oder darin suchen.

  • Python-Bibliothek. Sie können die Klasse TsbKaskoClient direkt in Ihrem eigenen Projekt verwenden.

Installation

Voraussetzung: uv. Es installiert auch Python.

Zum Testen ohne Installation:

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

Dauerhafte Installation:

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

oder mit pip:

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

Das Paket wurde noch nicht auf PyPI veröffentlicht. Sobald es veröffentlicht ist, werden uv tool install tsb-kasko-mcp und pip install tsb-kasko-mcp funktionieren; der Veröffentlichungs-Workflow ist im Repository bereit.

Für eine Entwicklungsinstallation aus dem Repository siehe Abschnitt Entwicklung.

MCP-Installation

Der Server unterstützt sowohl stdio als auch streamable HTTP-Transport, daher funktioniert er sowohl für Desktop-Clients als auch für gehostete Konnektoren.

Claude Code

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

Claude Desktop

Fügen Sie in die Datei claude_desktop_config.json ein:

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

Cursor / VS Code

Fügen Sie denselben mcpServers-Block in die Datei .cursor/mcp.json oder .vscode/mcp.json im Arbeitsbereich ein.

Gemini CLI

Fügen Sie in die Datei ~/.gemini/settings.json ein:

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

ChatGPT und andere entfernte Clients

ChatGPT-Konnektoren erreichen den Server über HTTP. Starten Sie den Server im HTTP-Modus:

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

oder mit einem beliebigen ASGI-Server:

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

Der Endpunkt wird standardmäßig unter http://server:8000/mcp bereitgestellt. Für den einfachsten Weg siehe Abschnitt Docker.

MCP-Werkzeuge

Werkzeug

Was es tut

kasko_lookup

Findet Fahrzeuge aus Freitext und gibt den Kaskowert jeder Übereinstimmung zurück. Dies ist das Hauptwerkzeug.

kasko_list_model_years

Gibt die von der Liste abgedeckten Modelljahre zurück. Abdeckung ab 2012.

kasko_list_brands

Listet die Marken eines Modelljahres auf.

kasko_list_models

Listet die Typen einer Marke in diesem Modelljahr auf.

kasko_get_value

Liest den Wert eines einzelnen Fahrzeugs mit bekannter Modell-ID.

kasko_archive_file

Analysiert die veröffentlichte Excel-Datei eines bestimmten Monats.

kasko_search_archive

Durchsucht die Liste eines vergangenen Monats.

kasko_download_archive

Lädt die Excel-Datei eines bestimmten Monats auf die Festplatte herunter.

Alle Werkzeuge außer kasko_download_archive sind mit readOnlyHint gekennzeichnet; der Client kann sie also ohne Bestätigung aufrufen.

Kommandozeilenverwendung

# 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

Beispielausgabe:

                      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│
└──────────────┴───────┴─────────────────────────────────────┴────────────────┘

Als Python-Bibliothek

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

Der Container stellt den MCP-Server über HTTP-Transport bereit. Er verwendet einen zweistufigen Build, läuft als nicht-Root-Benutzer und das Dateisystem ist schreibgeschützt.

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

Nur um das Image zu bauen und die CLI auszuführen:

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

Die Python-Version ist im Image mit ARG PYTHON_VERSION festgelegt und verwendet dieselbe Version wie .python-version im Repository.

Konfiguration

Alle Einstellungen können durch Umgebungsvariablen überschrieben werden.

Variable

Standard

Beschreibung

TSB_KASKO_BASE_URL

https://www.tsb.org.tr

Stamm-URL der TSB-Anwendung.

TSB_KASKO_TIMEOUT

30

Zeitüberschreitung pro Anfrage, Sekunden.

TSB_KASKO_MAX_RETRIES

3

Anzahl der Wiederholungen bei vorübergehenden Fehlern.

TSB_KASKO_CACHE

1

Wenn 0 gesetzt, wird der Cache vollständig deaktiviert.

TSB_KASKO_CACHE_TTL

21600

Lebensdauer des Caches für Marken- und Modelllisten, Sekunden.

TSB_KASKO_CACHE_DIR

~/.cache/tsb-kasko

Cache-Verzeichnis.

TSB_KASKO_TRANSPORT

stdio

MCP-Transport: stdio, http oder sse.

TSB_KASKO_HOST

127.0.0.1

Lauschadresse des HTTP-Transports.

TSB_KASKO_PORT

8000

Port des HTTP-Transports.

TSB_KASKO_MCP_PATH

/mcp

Endpunktpfad in der ASGI-Anwendung.

Verwendete TSB-Endpunkte

TSB veröffentlicht keinen API-Vertrag. Die folgenden Endpunkte werden von der Website-Frontend verwendet und erfordern keine Authentifizierung oder Cookies. Sie sind alle an einer Stelle in src/tsb_kasko/endpoints.py definiert.

Endpunkt

Parameter

Rückgabe

GET /InsuranceData/GetVehicleYearList

keine

Abgedeckte Modelljahre

GET /InsuranceData/GetVehicleBrandList

VehicleYear

Marken

GET /InsuranceData/GetVehicleModelList

vehicleYear, VehicleBrandId

Typen

GET /InsuranceData/GetInsuranceDatas

VehicleYear, VehicleModelId

Kaskowert und Fahrzeugcode

GET /InsuranceData/GetMonthList

keine

Archivmonate

GET /InsuranceData/GetInsuranceDataArchiveFile

Year, MonthId

Pfad der monatlichen Excel-Datei

Zwei Details sind bemerkenswert:

  1. Das Feld VehicleBrandCode in der Markenliste ist immer 0. Der tatsächliche Markencode, der in der Police steht, ist nur in der Antwort von GetInsuranceDatas gefüllt.

  2. Das Feld Id in GetMonthList ist kein Kalendermonat. Januar hat die ID 2, Oktober die ID 1. Daher berechnet der Client die Monats-ID nicht, sondern ermittelt sie aus der Live-Liste.

Projektstruktur

Alle drei Schnittstellen sind dünne Hüllen über demselben Kern. Daher leben sie alle in einem einzigen Repository: Wenn TSB einen Endpunkt umbenennt, wird die Korrektur in einer einzigen Datei vorgenommen, es ist keine Synchronisation von drei verschiedenen Versionen erforderlich.

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ı

Das gleiche Muster wird auch in den Projekten github/github-mcp-server, microsoft/playwright-mcp und grafana/mcp-grafana verwendet: gemeinsamer Kern mit mehreren Einstiegspunkten.

Entwicklung

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ı

Die Tests verwenden exakte Kopien der tatsächlichen Antworten von TSB, sodass die Tests brechen, wenn sich der Vertrag ändert. Es gibt keine Tests, die auf das Netzwerk zugreifen.

Gleiches Ergebnis unter Windows, macOS und Linux

Dieses Repository wurde so eingerichtet, dass es sich unter allen drei Betriebssystemen gleich verhält:

  • .python-version legt die Python-Version auf 3.14 fest; uv lädt sie bei Bedarf herunter. Der unterstützte Bereich des Pakets ist >=3.11 und CI testet alle vier Versionen.

  • .gitattributes speichert jede Textdatei im Repository mit LF. Selbst wenn core.autocrlf unter Windows aktiviert ist, gelangt kein CRLF ins Repository. Ein Schritt in CI überprüft dies zusätzlich.

  • .editorconfig legt Einrückung, Kodierung und Zeilenende unabhängig vom Editor fest.

  • Mit .devcontainer/ können Sie ohne Installation in einem Container entwickeln.

Details siehe CONTRIBUTING.md.

Häufig gestellte Fragen

Was ist der Kaskowert und wie wird er bestimmt? Es ist der von TSB monatlich veröffentlichte Referenzfahrzeugwert nach Marke und Typ. Versicherungsgesellschaften berechnen die Policenprämie und die Schadenszahlung auf der Grundlage dieses Betrags.

Wie erfahre ich den Kaskowert meines Fahrzeugs? Führen Sie den Befehl tsb-kasko lookup <Modelljahr> "<Marke und Typ>" aus oder installieren Sie den MCP-Server und fragen Sie Ihren Assistenten. Die offizielle Quelle ist immer tsb.org.tr.

Was ist der Fahrzeugcode in der Police? Es ist das vom Versicherer angeforderte Paar Markencode - Modellcode, z.B. 9-1616. Es wird im Feld vehicle_code der Ergebnisse zurückgegeben.

Welche Modelljahre werden abgedeckt? 2012 und später. Die aktuelle Liste können Sie mit tsb-kasko years anzeigen.

Kann ich auf die Liste eines vergangenen Monats zugreifen? Ja. tsb-kasko archive search 2025 2 --query "sahin" sucht in der Excel-Datei des vergangenen Monats, archive download lädt die Datei selbst herunter.

Ist dieses Projekt offiziell? Nein. Siehe den Haftungsausschluss unten.

Haftungsausschluss

Dieses Projekt ist nicht mit TSB verbunden und wird von TSB nicht unterstützt. Die Daten werden von der öffentlichen Seite von TSB bezogen. Nach eigenen Angaben von TSB übernimmt TSB keine Haftung für Folgen, die aus der Verwendung dieser Werte in Transaktionen entstehen. Die offizielle Quelle ist immer tsb.org.tr.

Da die Endpunkte von TSB nicht dokumentiert sind, können sie sich ohne Vorankündigung ändern. In einem solchen Fall reicht es aus, die Datei src/tsb_kasko/endpoints.py zu aktualisieren.

Beitrag und Lizenz

MIT wird unter der MIT-Lizenz veröffentlicht. Deutsche Übersetzung der Informationen: 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