Skip to main content
Glama
tsb-kasko-mcp

tsb-kasko-mcp

by the-up

tsb-kasko-mcp — MCP server and CLI for TSB Kasko Value List

An open-source MCP server, command-line tool, and Python client that queries the Kasko Value List published by the Turkish Insurance Association (TSB). You can ask "What is the insured value of a 2025 Audi A3?" from within Claude, ChatGPT, Gemini, and Cursor; type tsb-kasko lookup 2025 "audi a3" in the terminal; or use it as a library in your own Python project.

CI Python MCP License: MIT Test coverage

The kasko value list is the reference amount used to price every comprehensive insurance policy sold in Turkey. It also serves as the basis for the payout in case of total loss (total damage) or theft. This project converts the unauthenticated endpoints used by the TSB website's backend into a typed client.

Interface

How to run

For whom

MCP server

tsb-kasko-mcp

Claude, ChatGPT, Gemini, Cursor

Command line

tsb-kasko lookup 2025 "audi a3"

Terminal, scripts, CI

Python client

from tsb_kasko import TsbKaskoClient

Your own application

When the package is installed, both commands are available; no separate CLI package is needed.

Table of Contents

Related MCP server: DPVAT: Emissão de Guia

What it does

  • Query the insured value from an AI assistant. Ask in natural language from within Claude, ChatGPT, and Gemini; the model calls the tool and returns the current value.

  • Query from the terminal. The tsb-kasko lookup 2025 "audi a3 sportback" command prints the result as a table, JSON, or CSV.

  • Vehicle code for the policy. Results also include the brand code - model code pair that insurers ask for, e.g., 9-1616.

  • Historical lists. TSB republishes the list every month. You can download the Excel file for past months or search within it.

  • Python library. Use the TsbKaskoClient class directly in your own projects.

Installation

Prerequisite: uv. It also installs Python.

To try without installing:

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

For a permanent installation:

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

or with pip:

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

The package has not yet been published on PyPI. Once published, uv tool install tsb-kasko-mcp and pip install tsb-kasko-mcp will also work; the publishing workflow is ready in the repository.

For a development installation from the repository, see the Development section.

MCP setup

The server supports both stdio and streamable HTTP transports, so it works with both desktop clients and hosted connectors.

Claude Code

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

Claude Desktop

Add to 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

Add the same mcpServers block to .cursor/mcp.json or .vscode/mcp.json in your workspace.

Gemini CLI

Add to ~/.gemini/settings.json:

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

ChatGPT and other remote clients

ChatGPT connectors reach the server over HTTP. Run the server in HTTP mode:

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

or with any ASGI server:

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

The endpoint is published at http://server:8000/mcp by default. For the easiest way, see the Docker section.

MCP tools

Tool

What it does

kasko_lookup

Finds vehicles from free text and returns the insured value for each match. This is the main tool.

kasko_list_model_years

Returns the model years covered by the list. Coverage is 2012 and later.

kasko_list_brands

Lists the brands for a given model year.

kasko_list_models

Lists the types for a given brand and model year.

kasko_get_value

Reads the value of a single vehicle with a known model ID.

kasko_archive_file

Parses the published Excel file for a given month.

kasko_search_archive

Searches within a past month's list.

kasko_download_archive

Downloads the Excel file for a given month to disk.

All tools except kasko_download_archive are marked with readOnlyHint; that is, the client can call them without asking for confirmation.

Command-line usage

# 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

Example output:

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

As a Python library

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

The container publishes the MCP server with HTTP transport. It uses a multi-stage build, runs as a non-root user, and has a read-only filesystem.

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

To only build the image and run the CLI:

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

The Python version is pinned in the image via ARG PYTHON_VERSION and uses the same version as .python-version in the repository.

Configuration

All settings can be overridden with environment variables.

Variable

Default

Description

TSB_KASKO_BASE_URL

https://www.tsb.org.tr

Root address of the TSB application.

TSB_KASKO_TIMEOUT

30

Timeout per request, in seconds.

TSB_KASKO_MAX_RETRIES

3

Number of retries on transient errors.

TSB_KASKO_CACHE

1

Set to 0 to disable caching entirely.

TSB_KASKO_CACHE_TTL

21600

Cache lifetime for brand and model lists, in seconds.

TSB_KASKO_CACHE_DIR

~/.cache/tsb-kasko

Cache directory.

TSB_KASKO_TRANSPORT

stdio

MCP transport: stdio, http, or sse.

TSB_KASKO_HOST

127.0.0.1

Listening address for HTTP transport.

TSB_KASKO_PORT

8000

Port for HTTP transport.

TSB_KASKO_MCP_PATH

/mcp

Endpoint path in the ASGI application.

TSB endpoints used

TSB does not publish an API contract. The following endpoints are used by the site's frontend and require no authentication or cookies. They are all defined in one place in src/tsb_kasko/endpoints.py.

Endpoint

Parameters

Returns

GET /InsuranceData/GetVehicleYearList

none

Covered model years

GET /InsuranceData/GetVehicleBrandList

VehicleYear

Brands

GET /InsuranceData/GetVehicleModelList

vehicleYear, VehicleBrandId

Types

GET /InsuranceData/GetInsuranceDatas

VehicleYear, VehicleModelId

Insured value and vehicle code

GET /InsuranceData/GetMonthList

none

Archive months

GET /InsuranceData/GetInsuranceDataArchiveFile

Year, MonthId

Path to the monthly Excel file

Two details are noteworthy:

  1. The VehicleBrandCode field in the brand list always comes as 0. The actual brand code that appears on the policy is only populated in the GetInsuranceDatas response.

  2. The Id field in GetMonthList is not the calendar month. January has 2, October has 1. Therefore the client does not calculate the month ID; it resolves it from the live list.

Project structure

All three interfaces are thin shells on top of the same core. That is why they all live in a single repository: when TSB renames an endpoint, the fix is made in one file, and no synchronization of three separate versions is needed.

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ı

The same layout is used in the github/github-mcp-server, microsoft/playwright-mcp, and grafana/mcp-grafana projects: a shared core with multiple entry points on top.

Development

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ı

Tests use exact copies of real responses taken from TSB, so they break when the contract changes. There are no network-dependent tests.

Same results on Windows, macOS, and Linux

This repository is configured to behave identically on all three operating systems:

  • .python-version pins the Python version to 3.14; uv downloads it if needed. The package's supported range is >=3.11, and CI tests all four versions.

  • .gitattributes stores every text file with LF in the repository. Even if core.autocrlf is enabled on Windows, no CRLF enters the repository. A CI step additionally checks this.

  • .editorconfig fixes indentation, encoding, and line endings independently of the editor.

  • With .devcontainer/ you can develop inside a container without installing anything.

For details, see CONTRIBUTING.md.

FAQ

What is the insured value and how is it determined? It is the reference vehicle value published monthly by TSB, based on brand and type. Insurance companies calculate the policy premium and claim payment based on this value.

How can I find out my vehicle's insured value? Run tsb-kasko lookup <model_year> "<brand and type>" or set up the MCP server and ask your assistant. The official source is always tsb.org.tr.

What is the vehicle code on the policy? It is the brand code - model code pair that insurers ask for, e.g., 9-1616. It is returned in the vehicle_code field in the results.

Which model years are covered? 2012 and later. You can see the current list with tsb-kasko years.

Can I access a past month's list? Yes. tsb-kasko archive search 2025 2 --query "sahin" searches within the Excel file of a past month, and archive download downloads the file itself.

Is this project official? No. See the disclaimer below.

Disclaimer

This project is not affiliated with or endorsed by TSB. The data is taken from TSB's public page. According to TSB's own statement, TSB accepts no responsibility for the consequences of using these values in transactions. The official source is always tsb.org.tr.

Since the endpoints are not documented by TSB, they may change without notice. In such a case, updating src/tsb_kasko/endpoints.py is sufficient.

Contributing and license

Licensed under the MIT license. Turkish translation of the documentation: 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