Skip to main content
Glama
tsb-kasko-mcp

tsb-kasko-mcp

by the-up

tsb-kasko-mcp — MCP-сервер и CLI для списка страховых сумм каско TSB

Сервер с открытым исходным кодом MCP, инструмент командной строки и клиент Python для запроса Списка страховых сумм каско, публикуемого Турецкой ассоциацией страхования (TSB). С помощью Claude, ChatGPT, Gemini и Cursor можно спросить: «Сколько стоит страховка каско на Audi A3 2025 года?»; написать в терминале tsb-kasko lookup 2025 "audi a3"; или использовать как библиотеку в своём проекте Python.

CI Python MCP Лицензия: MIT Покрытие тестами

Список сумм каско — это эталонная стоимость, по которой оценивается каждый полис каско, продаваемый в Турции. Она также является основой для выплаты в случае полного ущерба (перт) и кражи. Этот проект превращает конечные точки, используемые в фоновом режиме веб-сайта TSB и не требующие аутентификации, в типизированный клиент.

Интерфейс

Как запустить

Для кого

MCP-сервер

tsb-kasko-mcp

Claude, ChatGPT, Gemini, Cursor

Командная строка

tsb-kasko lookup 2025 "audi a3"

Терминал, скрипт, CI

Клиент Python

from tsb_kasko import TsbKaskoClient

Ваше собственное приложение

При установке пакета появляются обе команды; устанавливать отдельный пакет CLI не нужно.

Содержание

Related MCP server: DPVAT: Emissão de Guia

Для чего это нужно

  • Запрос суммы каско через ИИ-ассистента. Задаёте вопрос на естественном языке в Claude, ChatGPT и Gemini, модель вызывает инструмент и возвращает актуальную сумму.

  • Запрос из терминала. Команда tsb-kasko lookup 2025 "audi a3 sportback" выводит таблицу, JSON или CSV напрямую.

  • Код транспортного средства в полисе. Результаты также содержат пару код марки - код модели, которую запрашивает страховщик, например 9-1616.

  • Архивные списки. TSB публикует список каждый месяц. Вы можете скачать Excel-файл за прошлые месяцы или выполнить поиск внутри него.

  • Библиотека Python. В своём проекте вы можете напрямую использовать класс TsbKaskoClient.

Установка

Предварительное условие: uv. Он также установит Python.

Для пробы без установки:

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

Постоянная установка:

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

или с помощью pip:

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

Пакет ещё не опубликован на PyPI. Когда будет опубликован, uv tool install tsb-kasko-mcp и pip install tsb-kasko-mcp также будут работать; рабочий процесс публикации готов в репозитории.

Инструкции по установке для разработки из репозитория см. в разделе Разработка.

Установка MCP

Сервер поддерживает как транспорт stdio, так и потоковый HTTP, поэтому он работает как с настольными клиентами, так и с хостингованными коннекторами.

Claude Code

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

Claude Desktop

Добавьте в файл 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

Добавьте тот же блок mcpServers в файл .cursor/mcp.json или .vscode/mcp.json в рабочей области.

Gemini CLI

Добавьте в файл ~/.gemini/settings.json:

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

ChatGPT и другие удалённые клиенты

Коннекторы ChatGPT подключаются к серверу через HTTP. Запустите сервер в режиме HTTP:

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

или с любым ASGI-сервером:

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

Конечная точка по умолчанию публикуется по адресу http://сервер:8000/mcp. Самый простой способ — см. раздел Docker.

Инструменты MCP

Инструмент

Что делает

kasko_lookup

Находит автомобиль по произвольному тексту и возвращает страховую сумму для каждого совпадения. Это основной инструмент.

kasko_list_model_years

Возвращает модельные годы, охватываемые списком. Охватывает 2012 год и более поздние.

kasko_list_brands

Перечисляет марки для данного модельного года.

kasko_list_models

Перечисляет типы для данной марки в данном модельном году.

kasko_get_value

Читает стоимость одного автомобиля с известным идентификатором модели.

kasko_archive_file

Анализирует опубликованный Excel-файл за определённый месяц.

kasko_search_archive

Выполняет поиск в списке за прошлый месяц.

kasko_download_archive

Скачивает Excel-файл за определённый месяц на диск.

Все инструменты, кроме kasko_download_archive, помечены как readOnlyHint; то есть клиент может вызывать их без запроса подтверждения.

Использование командной строки

# 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

Пример вывода:

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

Как библиотека 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

Контейнер публикует MCP-сервер через HTTP-транспорт. Использует двухэтапную сборку, работает от непривилегированного пользователя, файловая система только для чтения.

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

Чтобы только собрать образ и запустить CLI:

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

Версия Python фиксируется в образе через ARG PYTHON_VERSION и использует ту же версию, что и .python-version в репозитории.

Конфигурация

Все настройки можно переопределить через переменные окружения.

Переменная

Значение по умолчанию

Описание

TSB_KASKO_BASE_URL

https://www.tsb.org.tr

Корневой адрес приложения TSB.

TSB_KASKO_TIMEOUT

30

Тайм-аут на запрос, секунды.

TSB_KASKO_MAX_RETRIES

3

Количество попыток при временных ошибках.

TSB_KASKO_CACHE

1

При 0 кэш полностью отключается.

TSB_KASKO_CACHE_TTL

21600

Время жизни кэша для списков марок и моделей, секунды.

TSB_KASKO_CACHE_DIR

~/.cache/tsb-kasko

Директория кэша.

TSB_KASKO_TRANSPORT

stdio

Транспорт MCP: stdio, http или sse.

TSB_KASKO_HOST

127.0.0.1

Адрес прослушивания для HTTP-транспорта.

TSB_KASKO_PORT

8000

Порт для HTTP-транспорта.

TSB_KASKO_MCP_PATH

/mcp

Путь конечной точки в ASGI-приложении.

Используемые конечные точки TSB

TSB не публикует контракт API. Ниже приведены конечные точки, используемые внешним интерфейсом сайта, не требующие аутентификации и куки. Все они определены в одном месте в src/tsb_kasko/endpoints.py.

Конечная точка

Параметры

Возвращает

GET /InsuranceData/GetVehicleYearList

нет

Охватываемые модельные годы

GET /InsuranceData/GetVehicleBrandList

VehicleYear

Марки

GET /InsuranceData/GetVehicleModelList

vehicleYear, VehicleBrandId

Типы

GET /InsuranceData/GetInsuranceDatas

VehicleYear, VehicleModelId

Сумма каско и код автомобиля

GET /InsuranceData/GetMonthList

нет

Архивные месяцы

GET /InsuranceData/GetInsuranceDataArchiveFile

Year, MonthId

Путь к ежемесячному Excel-файлу

Две детали примечательны:

  1. Поле VehicleBrandCode в списке марок всегда равно 0. Реальный код марки, указанный в полисе, приходит только в ответе GetInsuranceDatas.

  2. Поле Id в GetMonthList не является номером месяца календаря. Январь имеет идентификатор 2, Октябрь — 1. Поэтому клиент не вычисляет идентификатор месяца, а получает его из живого списка.

Структура проекта

Все три интерфейса — это тонкие обёртки поверх одного и того же ядра. Поэтому все они живут в одном репозитории: если TSB переименует какую-либо конечную точку, исправление вносится в один файл, и не требуется синхронизация трёх отдельных версий.

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ı

Такая же структура используется в проектах github/github-mcp-server, microsoft/playwright-mcp и grafana/mcp-grafana: общее ядро, поверх него несколько точек входа.

Разработка

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ı

Тесты используют точные копии реальных ответов от TSB, поэтому при изменении контракта тесты сломаются. Нет тестов, выходящих в сеть.

Одинаковый результат на Windows, macOS и Linux

Этот репозиторий настроен для одинакового поведения на всех трёх операционных системах:

  • .python-version фиксирует версию Python на 3.14; uv при необходимости загрузит её. Однако поддерживаемый пакетом диапазон — >=3.11, и CI тестирует все четыре версии.

  • .gitattributes хранит каждый текстовый файл в репозитории с окончанием строки LF. Даже если core.autocrlf включён в Windows, в репозиторий не попадут символы CRLF. В CI есть отдельный шаг для проверки этого.

  • .editorconfig фиксирует отступы, кодировку и конец строки независимо от редактора.

  • С помощью .devcontainer/ вы можете разрабатывать внутри контейнера, ничего не устанавливая.

Подробности см. в CONTRIBUTING.md.

Часто задаваемые вопросы

Что такое стоимость каско и как она определяется? Это эталонная стоимость транспортного средства по марке и типу, публикуемая TSB ежемесячно. Страховые компании рассчитывают на основе этой стоимости премию полиса и выплату по ущербу.

Как узнать стоимость каско моего автомобиля? Выполните команду tsb-kasko lookup <модельный_год> "<марка и тип>" или установите MCP-сервер и спросите своего ассистента. Официальный источник всегда — tsb.org.tr.

Что такое код транспортного средства в полисе? Это пара код марки - код модели, которую запрашивает страховщик, например 9-1616. В результатах возвращается в поле vehicle_code.

Какие модельные годы охватываются? 2012 и более поздние. Актуальный список можно увидеть с помощью tsb-kasko years.

Могу ли я получить список за прошлый месяц? Да. tsb-kasko archive search 2025 2 --query "sahin" выполняет поиск в Excel-файле за прошлый месяц, а archive download скачивает сам файл.

Этот проект официальный? Нет. См. отказ от ответственности ниже.

Отказ от ответственности

Этот проект не связан с TSB и не поддерживается TSB. Данные берутся с общедоступной страницы TSB. По собственному заявлению TSB, они не несут ответственности за последствия использования этих значений в сделках. Официальный источник всегда — tsb.org.tr.

Поскольку конечные точки не задокументированы TSB, они могут измениться без предупреждения. В таком случае достаточно обновить файл src/tsb_kasko/endpoints.py.

Вклад и лицензия

MIT опубликовано под лицензией. Перевод на турецкий язык: 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