Skip to main content
Glama
tsb-kasko-mcp

tsb-kasko-mcp

by the-up

tsb-kasko-mcp — Servidor MCP y CLI para la Lista de Valores de Seguro de Automóviles TSB

Un servidor MCP, herramienta de línea de comandos y cliente Python de código abierto para consultar la Lista de Valores de Seguro de Automóviles publicada por la Asociación de Seguros de Turquía (TSB). Puede preguntar "¿Cuánto cuesta el seguro de un Audi A3 modelo 2025?" desde Claude, ChatGPT, Gemini y Cursor; escribir tsb-kasko lookup 2025 "audi a3" en la terminal; o usarlo como biblioteca en su propio proyecto Python.

CI Python MCP Licencia: MIT Cobertura de pruebas

La lista de valores de seguro es el precio de referencia con el que se fija cada póliza de seguro de automóvil vendida en Turquía. También es la base del monto a pagar en caso de pérdida total (daño total) y robo. Este proyecto convierte los endpoints que el sitio web de TSB utiliza en segundo plano y que no requieren autenticación en un cliente tipado.

Interfaz

Cómo ejecutar

Para quién

Servidor MCP

tsb-kasko-mcp

Claude, ChatGPT, Gemini, Cursor

Línea de comandos

tsb-kasko lookup 2025 "audi a3"

Terminal, scripts, CI

Cliente Python

from tsb_kasko import TsbKaskoClient

Su propia aplicación

Cuando se instala el paquete, vienen dos comandos; no es necesario instalar un paquete CLI aparte.

Índice

Related MCP server: DPVAT: Emissão de Guia

¿Para qué sirve?

  • Consultar el valor del seguro desde un asistente de IA. Pregunta en lenguaje natural desde Claude, ChatGPT y Gemini, el modelo llama a la herramienta y devuelve el valor actual.

  • Consultar desde la terminal. El comando tsb-kasko lookup 2025 "audi a3 sportback" imprime directamente la tabla, JSON o CSV.

  • Código del vehículo en la póliza. Los resultados también incluyen el par código de marca - código de modelo que pregunta la aseguradora, por ejemplo 9-1616.

  • Listas históricas. TSB vuelve a publicar la lista cada mes. Puede descargar el archivo Excel de meses anteriores o buscar dentro de él.

  • Biblioteca Python. Puede usar la clase TsbKaskoClient directamente en su propio proyecto.

Instalación

Requisito previo: uv. También instala Python.

Para probar sin instalar:

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

Instalación permanente:

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

o con pip:

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

El paquete aún no se ha publicado en PyPI. Cuando se publique, también funcionarán uv tool install tsb-kasko-mcp y pip install tsb-kasko-mcp; el flujo de trabajo de publicación está listo en el repositorio.

Para la instalación de desarrollo desde el repositorio, consulte la sección Desarrollo.

Configuración de MCP

El servidor admite tanto el transporte stdio como HTTP transmisible, por lo que funciona tanto para clientes de escritorio como para conectores alojados.

Claude Code

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

Claude Desktop

Agregue al archivo 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

Agregue el mismo bloque mcpServers al archivo .cursor/mcp.json o .vscode/mcp.json en el espacio de trabajo.

Gemini CLI

Agregue al archivo ~/.gemini/settings.json:

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

ChatGPT y otros clientes remotos

Los conectores de ChatGPT acceden al servidor a través de HTTP. Ejecute el servidor en modo HTTP:

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

o con cualquier servidor ASGI:

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

El endpoint se publica por defecto en http://servidor:8000/mcp. Para la forma más sencilla, consulte la sección Docker.

Herramientas MCP

Herramienta

Qué hace

kasko_lookup

Encuentra vehículos a partir de texto libre y devuelve el valor del seguro de cada coincidencia. Es la herramienta principal.

kasko_list_model_years

Devuelve los años de modelo cubiertos por la lista. El alcance es 2012 y posteriores.

kasko_list_brands

Lista las marcas de un año de modelo.

kasko_list_models

Lista los tipos de una marca para ese año de modelo.

kasko_get_value

Lee el valor de un solo vehículo del que se conoce el ID del modelo.

kasko_archive_file

Analiza el archivo Excel publicado de un mes determinado.

kasko_search_archive

Busca dentro de la lista de un mes anterior.

kasko_download_archive

Descarga el archivo Excel de un mes determinado al disco.

Todas las herramientas excepto kasko_download_archive están marcadas con readOnlyHint; es decir, el cliente puede llamarlas sin solicitar confirmación.

Uso desde la línea de comandos

# 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

Ejemplo de salida:

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

Como biblioteca 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

El contenedor publica el servidor MCP con transporte HTTP. Utiliza compilación en dos etapas, se ejecuta con un usuario no root y el sistema de archivos es de solo lectura.

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

Para solo compilar la imagen y ejecutar la CLI:

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

La versión de Python está fijada en la imagen con ARG PYTHON_VERSION y usa la misma versión que .python-version en el repositorio.

Configuración

Todas las configuraciones se pueden anular con variables de entorno.

Variable

Valor por defecto

Descripción

TSB_KASKO_BASE_URL

https://www.tsb.org.tr

Dirección raíz de la aplicación TSB.

TSB_KASKO_TIMEOUT

30

Tiempo de espera por solicitud, en segundos.

TSB_KASKO_MAX_RETRIES

3

Número de reintentos en errores temporales.

TSB_KASKO_CACHE

1

Si se establece en 0, la caché se desactiva por completo.

TSB_KASKO_CACHE_TTL

21600

Tiempo de vida de la caché para listas de marcas y modelos, en segundos.

TSB_KASKO_CACHE_DIR

~/.cache/tsb-kasko

Directorio de caché.

TSB_KASKO_TRANSPORT

stdio

Transporte MCP: stdio, http o sse.

TSB_KASKO_HOST

127.0.0.1

Dirección de escucha del transporte HTTP.

TSB_KASKO_PORT

8000

Puerto del transporte HTTP.

TSB_KASKO_MCP_PATH

/mcp

Ruta del endpoint en la aplicación ASGI.

Endpoints TSB utilizados

TSB no publica un contrato de API. Los siguientes endpoints son los que utiliza el frontend del sitio, no requieren autenticación ni cookies. Todos están definidos en un solo lugar en src/tsb_kasko/endpoints.py.

Endpoint

Parámetros

Devuelve

GET /InsuranceData/GetVehicleYearList

ninguno

Años de modelo cubiertos

GET /InsuranceData/GetVehicleBrandList

VehicleYear

Marcas

GET /InsuranceData/GetVehicleModelList

vehicleYear, VehicleBrandId

Tipos

GET /InsuranceData/GetInsuranceDatas

VehicleYear, VehicleModelId

Valor del seguro y código del vehículo

GET /InsuranceData/GetMonthList

ninguno

Meses de archivo

GET /InsuranceData/GetInsuranceDataArchiveFile

Year, MonthId

Ruta del archivo Excel mensual

Dos detalles son notables:

  1. El campo VehicleBrandCode en la lista de marcas siempre viene como 0. El código de marca real que aparece en la póliza solo viene completo en la respuesta de GetInsuranceDatas.

  2. El campo Id en GetMonthList no es el mes calendario. Enero tiene el ID 2, octubre tiene el ID 1. Por eso el cliente no calcula el ID del mes, sino que lo resuelve desde la lista en vivo.

Estructura del proyecto

Las tres interfaces son capas delgadas sobre el mismo núcleo. Por eso todas viven en un solo repositorio: cuando TSB renombra un endpoint, la corrección se hace en un solo archivo, no es necesario sincronizar tres versiones separadas.

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ı

El mismo diseño se utiliza en los proyectos github/github-mcp-server, microsoft/playwright-mcp y grafana/mcp-grafana: núcleo común, múltiples puntos de entrada encima.

Desarrollo

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ı

Las pruebas utilizan copias exactas de respuestas reales obtenidas de TSB, por lo que si el contrato cambia, las pruebas fallan. No hay pruebas que hagan llamadas de red.

Mismos resultados en Windows, macOS y Linux

Este repositorio está configurado para comportarse igual en los tres sistemas operativos:

  • .python-version fija la versión de Python en 3.14; uv la descarga si es necesario. El rango compatible del paquete es >=3.11 y CI prueba las cuatro versiones.

  • .gitattributes almacena cada archivo de texto en el repositorio con LF. Incluso si core.autocrlf está activado en Windows, no se introducen CRLF en el repositorio. En CI, un paso lo verifica adicionalmente.

  • .editorconfig fija la indentación, codificación y final de línea independientemente del editor.

  • Con .devcontainer/ puede desarrollar dentro de un contenedor sin instalar nada.

Para más detalles, consulte CONTRIBUTING.md.

Preguntas frecuentes

¿Qué es el valor del seguro y cómo se determina? Es el precio de referencia del vehículo por marca y tipo que TSB publica cada mes. Las compañías de seguros calculan la prima de la póliza y el pago de siniestros basándose en este valor.

¿Cómo puedo saber el valor del seguro de mi vehículo? Ejecute el comando tsb-kasko lookup <año_modelo> "<marca y tipo>" o instale el servidor MCP y pregunte a su asistente. La fuente oficial es siempre tsb.org.tr.

¿Qué es el código del vehículo en la póliza? Es el par código de marca - código de modelo que pregunta la aseguradora, por ejemplo 9-1616. En los resultados aparece en el campo vehicle_code.

¿Qué años de modelo están cubiertos? 2012 y posteriores. Puede ver la lista actual con tsb-kasko years.

¿Puedo acceder a la lista de un mes anterior? Sí. tsb-kasko archive search 2025 2 --query "sahin" busca en el archivo Excel del mes anterior, y archive download descarga el archivo en sí.

¿Este proyecto es oficial? No. Consulte el aviso de responsabilidad a continuación.

Aviso de responsabilidad

Este proyecto no está afiliado ni respaldado por TSB. Los datos se obtienen de la página pública de TSB. Según la propia declaración de TSB, esta no asume responsabilidad por las consecuencias derivadas del uso de estos valores en transacciones. La fuente oficial es siempre tsb.org.tr.

Como los endpoints no están documentados por TSB, pueden cambiar sin previo aviso. En tal caso, basta con actualizar el archivo src/tsb_kasko/endpoints.py.

Contribución y licencia

MIT es la licencia bajo la que se publica. Traducción informativa al turco: 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