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.

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.

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

Índice

• ¿Para qué sirve?

• Instalación

• Configuración de MCP

• Herramientas MCP

• Uso desde la línea de comandos

• Como biblioteca Python

• Docker

• Configuración

• Endpoints TSB utilizados

• Estructura del proyecto

• Desarrollo

• Preguntas frecuentes

• Aviso de responsabilidad

Related MCP server: RACV Insurance MCP Server

¿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

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.

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.

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

• Guía de contribución: CONTRIBUTING.md

• Código de conducta: CODE_OF_CONDUCT.md

• Política de seguridad: SECURITY.md

• Registro de cambios: CHANGELOG.md

MIT es la licencia bajo la que se publica. Traducción informativa al turco: docs/lisans.md.