tsb-kasko-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@tsb-kasko-mcp 2024 model Tesla Model Y'nin kasko değeri ne kadar?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Interface | How to run | For whom |
MCP server |
| Claude, ChatGPT, Gemini, Cursor |
Command line |
| Terminal, scripts, CI |
Python client |
| 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 codepair 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
TsbKaskoClientclass 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-mcpor with pip:
pip install git+https://github.com/hmtkyn/tsb-kasko-mcpThe package has not yet been published on PyPI. Once published,
uv tool install tsb-kasko-mcpandpip install tsb-kasko-mcpwill 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-mcpClaude 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-mcpor with any ASGI server:
uvicorn tsb_kasko.asgi:app --host 0.0.0.0 --port 8000The endpoint is published at http://server:8000/mcp by default. For the easiest way, see the Docker section.
MCP tools
Tool | What it does |
| Finds vehicles from free text and returns the insured value for each match. This is the main tool. |
| Returns the model years covered by the list. Coverage is 2012 and later. |
| Lists the brands for a given model year. |
| Lists the types for a given brand and model year. |
| Reads the value of a single vehicle with a known model ID. |
| Parses the published Excel file for a given month. |
| Searches within a past month's list. |
| 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 8000Example 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/mcpTo 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 |
|
| Root address of the TSB application. |
|
| Timeout per request, in seconds. |
|
| Number of retries on transient errors. |
|
| Set to |
|
| Cache lifetime for brand and model lists, in seconds. |
|
| Cache directory. |
|
| MCP transport: |
|
| Listening address for HTTP transport. |
|
| Port for HTTP transport. |
|
| 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 |
| none | Covered model years |
|
| Brands |
|
| Types |
|
| Insured value and vehicle code |
| none | Archive months |
|
| Path to the monthly Excel file |
Two details are noteworthy:
The
VehicleBrandCodefield in the brand list always comes as0. The actual brand code that appears on the policy is only populated in theGetInsuranceDatasresponse.The
Idfield inGetMonthListis not the calendar month. January has2, October has1. 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 installuv 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-versionpins the Python version to 3.14;uvdownloads it if needed. The package's supported range is>=3.11, and CI tests all four versions..gitattributesstores every text file with LF in the repository. Even ifcore.autocrlfis enabled on Windows, no CRLF enters the repository. A CI step additionally checks this..editorconfigfixes 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.
Available Tools
8 toolskasko_archive_fileARead-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_valueARead-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_brandsARead-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_modelsARead-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_yearsARead-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_lookupARead-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_archiveARead-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
Scored across 8 tools
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.
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.
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.
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
Related MCP Connectors
Pay-per-use tool marketplace for AI agents. Search, price-check, and call APIs via MCP.
Real, bindable home & auto insurance quotes via MCP — actual carrier rates, not estimates. Texas today, expanding across the US. AI agents can check eligibility, run a live multi-carrier quote, compare options (carrier names hidden until bind), and hand the customer a secure link where a licensed agent finalizes coverage — never an automated purchase. No sign-up or API key required; optional free partner keys for integrators.
SmartMoney77 MCP v0.6.0 — 14 public tools that turn financial questions into exact numbers and citable links. New: historical_investment_return and compare_investments, which compute "what if I had invested" results from real yearly price data. Also compound interest, FIRE number, credit-card payoff, emergency fund, inflation, latte factor, investment fees, cost of waiting, plus discovery/deep-link/share-pack tools for a catalog of calculators in 6 languages (he/en/ar/es/pt/in). Public, no login. Endpoint: https://smartmoney77.com/mcp
Unofficial CarsXE MCP — wraps the CarsXE Vehicle Data API (carsxe.com)
Related MCP Servers
- AlicenseAqualityCmaintenanceMCP 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.10MIT
- AlicenseNot gradedqualityDmaintenanceRead-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
- AlicenseAqualityBmaintenanceEnables product search, store price comparison, basket comparison, and price history review using Market Fiyatı data through a stdio MCP server.15299 npmMIT
- AlicenseAqualityBmaintenanceEnables 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.1897 PyPI1PolyForm Noncommercial 1.0.0