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.

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.

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

Table of Contents

• What it does

• Installation

• MCP setup

• MCP tools

• Command-line usage

• As a Python library

• Docker

• Configuration

• TSB endpoints used

• Project structure

• Development

• FAQ

• Disclaimer

Related MCP server: RACV Insurance MCP Server

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

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.

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.

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

• Contribution guide: CONTRIBUTING.md

• Code of conduct: CODE_OF_CONDUCT.md

• Security policy: SECURITY.md

• Changelog: CHANGELOG.md

Licensed under the MIT license. Turkish translation of the documentation: docs/lisans.md.