lk-tko-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., "@lk-tko-mcp Check the current debt for contragent with INN 7701234567"
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.
lk-tko-mcp
An MCP server (Model Context Protocol) in Python that gives Claude tool access to the LK system (personal account, project lk-tko-v2).
What it is and why
MCP is an open protocol through which an external process gives the LLM a set of “tools”: ordinary functions with typed arguments. By connecting the server to Claude Code, you can ask Claude to call a specific function (“get counterparty status by INN”, “calculate penalties for a period for lkUser”, etc.) instead of explaining the context in text or manually digging into the DB/code every time.
The goal of this pet project is to build a reusable tool layer over the LK business logic that you can use from any future Claude Code session, not just inside the main repository.
Related MCP server: MikroCLAW
Stack
Python 3.10+, dependency manager —
uvSDK:
mcp[cli](v2, packagemcp==2.1.0), classmcp.server.MCPServerTransport: stdio (Claude Code launches the process and communicates with it over stdin/stdout)
Integration stack
The first tool (get_contragent_status) talks to the CUBA REST API v2 of lk-tko-v2 (OAuth2 password grant + generic entity search on rtneo$Contragent) — not directly to the DB. The request format is confirmed by working examples from curls.txt in the lk-tko-v2 repository.
Structure
lk-tko-mcp/
├── server.py # MCPServer + @mcp.tool() функции — вся логика инструментов
├── lk_client.py # REST-клиент к lk-tko-v2 (OAuth2 + entity search)
├── run.py # точка входа, которую регистрирует Claude Code
├── .env.example # шаблон переменных окружения для доступа к ЛК (реальный .env не коммитится)
├── pyproject.toml
└── uv.lockRunning and verifying locally
uv run mcp dev run.py # открывает MCP Inspector в браузере — можно вручную вызывать toolsConnecting to Claude Code
claude mcp add lk-tko-mcp -- uv run run.py
claude mcp list # проверить, что статус ConnectedDevelopment plan
Scaffold — done. A server with
pingandget_contragent_status; runs locally and via Inspector.REST client — done.
lk_client.py: OAuth2 password grant with token caching +search_entity()on top of CUBA REST v2.First real integration — done and verified live.
get_contragent_statusactually calls the lk-tko-v2 REST API vialk_client.search_entity("rtneo$Contragent", ...); verified via MCP Inspector with real data from the test environment.Connecting to Claude Code — done.
claude mcp add lk-tko-mcp -- uv run run.py, status✔ Connected. A guide for onboarding other developers — seeONBOARDING.md.Debt/billing (Priority 1 from RESEARCH.md) — done, 6 of 7 verified.
get_contragent_debt,get_debt_by_phone,get_debt_by_email,get_serviced_periods,get_calculation_amount_type,get_contract,get_fine_details— all implemented via two new REST helpers inlk_client.py(call_v3for custom v3 controllers,call_servicefor declarative v2 services).get_contragent_billsis implemented but blocked by a bug on the lk-tko-v2 side (see note below).get_calculations_tabs,get_debt_breakdown_by_real_estate,find_contragents_with_debt_older_than— not implemented, they have no REST wrapper in lk-tko-v2 at all (confirmed by grep across the entire repository).
Known issues
get_contragent_billsfails with 500. A bug on the lk-tko-v2 side:BillRepository.getBillsByContragentAndPeriod(line 71) references a nonexistent aliasb.documentNumberinstead ofe.documentNumber— this breaks JPQL compilation on any call to/app/rest/v3/bill. A separate task has been filed to fix it in lk-tko-v2; our code is not at fault here.
Expanding the toolset — one tool per specific recurring scenario (e.g., period/penalties for lkUser — see project memory
project_lk_user_config), don't abstract in advance.(Optional) team access —
claude mcp add lk-tko-mcp --scope project -- uv run run.pywill create.mcp.jsonin the repository, which can be committed (without secrets).
Verification (after filling in .env)
# 1. Юнит-уровень, без Claude
uv run python -c "from lk_client import search_entity; print(search_entity('rtneo$Contragent', [{'property':'inn','operator':'=','value':'<реальный ИНН>'}]))"
# 2. Через MCP Inspector
uv run mcp dev run.py
# 3. End-to-end
claude mcp add lk-tko-mcp -- uv run run.py
claude mcp listSecurity notes
.envis not committed; real secrets (client_id/secret, login/password) are stored only locally.By default, point to the local dev instance of lk-tko-v2 (
http://localhost:8080) rather than staging/prod — there may be non-anonymized personal data there.The
Contragententity has no pre-confirmed "status" field —get_contragent_statusreturns the found entity in full; the field for the real status needs to be determined based on the actual REST API response.
Available Tools
10 toolsget_calculation_amount_typeC
Тип расчёта начислений и текущий долг по лицевому счёту/ИНН.
Inputs: pa_or_inn (required).
get_contractB
Список договоров контрагента с суммами начислений/платежей/пеней/долга.
contragent_id — UUID контрагента (см. поле "id" в get_contragent_status).
Inputs: contragent_id (required).
get_contragent_billsB
Счета контрагента за период.
contragent_id — UUID контрагента (см. поле "id" в get_contragent_status). date_from/date_to — даты в формате dd.MM.yyyy.
Inputs: contragent_id (required), date_to, is_paid, date_from.
get_contragent_debtA
Долг контрагента (основной долг, пени, госпошлина) по лицевому счёту или ИНН.
Inputs: pa_or_inn (required).
get_contragent_statusB
Найти контрагента ЛК по ИНН и вернуть его данные.
Возвращает найденную сущность Contragent целиком через REST API lk-tko-v2 — отдельного поля "статус" может не быть, это нужно смотреть по реальным данным, которые вернёт CUBA REST.
Inputs: inn (required).
get_debt_by_emailB
Долг по всем лицевым счетам, привязанным к email.
Inputs: email (required).
get_debt_by_phoneB
Долг по всем лицевым счетам, привязанным к телефону.
Inputs: phone (required).
get_fine_detailsA
Детализация пеней по лицевому счёту за период, по договорам и месяцам.
date_from/date_to — даты в формате dd.MM.yyyy.
Inputs: date_to (required), date_from (required), personal_account (required).
get_serviced_periodsB
Периоды обслуживания (даты начала/окончания) лицевого счёта или ИНН.
Inputs: pa_or_inn (required).
pingA
Проверка того, что сервер жив и подключён.
Inputs: no named parameters. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
There are several debt-related tools (get_contragent_debt, get_debt_by_phone, get_debt_by_email, get_calculation_amount_type, get_contract) whose outputs overlap in debt/penalty figures; descriptions clarify different lookup keys or levels, but an agent could still struggle to choose among them. ping and the document/period tools are clearly distinct.
All tools follow a get_ prefix and snake_case, and most use a readable get_<resource>_<detail> or get_<detail>_by_<identifier> pattern. The deviations are minor: ping has no get_, and names like get_calculation_amount_type are less intuitive than the rest.
Ten tools is a reasonable size for a debt/contract lookup server. Each tool covers a distinct query need without excessive redundancy or an overwhelming surface.
The set provides solid read-only coverage: contragent lookup, debt by multiple identifiers, bills, contracts, service periods, and fine details. A minor gap is the lack of a direct debt lookup by contragent UUID, which would require using an INN from get_contragent_status as a workaround.
Related MCP Connectors
Remote MCP utilities for agents: structured data, commerce checks, and x402 paid API discovery.
One MCP endpoint for Claude, GPT & Gemini: 100+ tools + no-code connectors + agent workers.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
Pay-per-use tool marketplace for AI agents. Search, price-check, and call APIs via MCP.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables Claude to interact with Acumatica ERP through a remote MCP server with per-user OAuth, role-based access, and 44 tools for querying and managing ERP data.21Apache 2.0
- AlicenseBqualityCmaintenanceMCP server that enables Claude Code to access, monitor, and manage MikroTik RouterOS devices via its REST API, with 92 tools for read-only and optional write operations.92Apache 2.0
- FlicenseNot gradedqualityDmaintenanceConnects Claude to the Qoyod accounting system via its REST API, enabling natural language management of customers, invoices, vendors, journal entries, and other accounting resources through MCP tools.-
- AlicenseNot gradedqualityCmaintenanceEnables Claude Code to access amoCRM data such as pipelines, deals, contacts, and users via the MCP protocol.ISC