tsb-kasko-mcp
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.
Interfaz | Cómo ejecutar | Para quién |
Servidor MCP |
| Claude, ChatGPT, Gemini, Cursor |
Línea de comandos |
| Terminal, scripts, CI |
Cliente Python |
| 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 modeloque pregunta la aseguradora, por ejemplo9-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
TsbKaskoClientdirectamente 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-mcpo con pip:
pip install git+https://github.com/hmtkyn/tsb-kasko-mcpEl paquete aún no se ha publicado en PyPI. Cuando se publique, también funcionarán
uv tool install tsb-kasko-mcpypip 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-mcpClaude 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-mcpo con cualquier servidor ASGI:
uvicorn tsb_kasko.asgi:app --host 0.0.0.0 --port 8000El 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 |
| Encuentra vehículos a partir de texto libre y devuelve el valor del seguro de cada coincidencia. Es la herramienta principal. |
| Devuelve los años de modelo cubiertos por la lista. El alcance es 2012 y posteriores. |
| Lista las marcas de un año de modelo. |
| Lista los tipos de una marca para ese año de modelo. |
| Lee el valor de un solo vehículo del que se conoce el ID del modelo. |
| Analiza el archivo Excel publicado de un mes determinado. |
| Busca dentro de la lista de un mes anterior. |
| 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 8000Ejemplo 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/mcpPara 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 |
|
| Dirección raíz de la aplicación TSB. |
|
| Tiempo de espera por solicitud, en segundos. |
|
| Número de reintentos en errores temporales. |
|
| Si se establece en |
|
| Tiempo de vida de la caché para listas de marcas y modelos, en segundos. |
|
| Directorio de caché. |
|
| Transporte MCP: |
|
| Dirección de escucha del transporte HTTP. |
|
| Puerto del transporte HTTP. |
|
| 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 |
| ninguno | Años de modelo cubiertos |
|
| Marcas |
|
| Tipos |
|
| Valor del seguro y código del vehículo |
| ninguno | Meses de archivo |
|
| Ruta del archivo Excel mensual |
Dos detalles son notables:
El campo
VehicleBrandCodeen la lista de marcas siempre viene como0. El código de marca real que aparece en la póliza solo viene completo en la respuesta deGetInsuranceDatas.El campo
IdenGetMonthListno es el mes calendario. Enero tiene el ID2, octubre tiene el ID1. 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 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ı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-versionfija la versión de Python en 3.14;uvla descarga si es necesario. El rango compatible del paquete es>=3.11y CI prueba las cuatro versiones..gitattributesalmacena cada archivo de texto en el repositorio con LF. Incluso sicore.autocrlfestá activado en Windows, no se introducen CRLF en el repositorio. En CI, un paso lo verifica adicionalmente..editorconfigfija 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.
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