Kontomierz-MCP

Servidor MCP (Model Context Protocol) para Kontomierz.pl, una plataforma polaca de finanzas personales. Permite que asistentes de IA (Claude Desktop, LibreChat, Cline) lean y gestionen tus cuentas bancarias, transacciones, presupuestos y pagos programados, todo a través de una única API. Desarrollado en Python, se ejecuta localmente o en Docker.

GitHubPrueba este MCPPatrocinado

Documentación

Kontomierz-MCP

Servidor MCP (Model Context Protocol) para Kontomierz.pl, una plataforma polaca de finanzas personales. Expone 27 herramientas para cuentas, transacciones, presupuestos, pagos programados, datos de referencia, gráficos e historial de patrimonio, de modo que los asistentes compatibles con MCP puedan trabajar con Kontomierz a través de un único servidor local.

La versión 2.0.0 reemplaza el antiguo puente SSE/REST por stdio y HTTP Streamable autenticado y restringido a loopback. Las fechas públicas usan ISO YYYY-MM-DD, los meses presupuestarios usan YYYY-MM, y las operaciones de escritura están deshabilitadas a menos que el operador del servidor las habilite explícitamente.

Requisitos

Python 3.11+ para uso local. Los bloqueos de dependencias Linux x64 exactos del repositorio cubren Python 3.11, 3.12 y 3.13.
Una cuenta de Kontomierz.pl con una clave de API, salvo que se use el backend simulado determinista.
Docker solo si quieres reproducir o ejecutar el artefacto de contenedor exacto.

Inicio rápido

1. Instalar y configurar

git clone https://github.com/paulomac1000/kontomierz-mcp.git
cd kontomierz-mcp

python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e .

cp .env.example .env
# Edit .env and set KONTOMIERZ_API_KEY

El servidor lee .env del directorio de trabajo actual sin sobrescribir las variables ya presentes en el entorno del proceso.

Para una demo local sin E/S, no se necesita una clave de API real:

KONTOMIERZ_MOCK_DATA=1 kontomierz-mcp

2. Ejecutar con stdio

Stdio es el transporte predeterminado y recomendado para un cliente MCP local:

kontomierz-mcp

Las herramientas de lectura están disponibles de inmediato. Las escrituras ordinarias requieren la puerta de operador independiente:

export ENABLE_WRITE_OPERATIONS=1
kontomierz-mcp

Las herramientas destructivas requieren la puerta de escritura y listas de permitidos de capacidades/recursos exactas propiedad del servidor. Por ejemplo:

export ENABLE_WRITE_OPERATIONS=1
export MCP_STDIO_ALLOWED_DESTRUCTIVE_CAPABILITIES=destroy_wallet
export MCP_STDIO_ALLOWED_DESTRUCTIVE_RESOURCES=wallet:123
kontomierz-mcp

No se aceptan comodines para recursos destructivos.

3. Conectar un cliente MCP

Un cliente stdio puede iniciar el ejecutable directamente. Por ejemplo, una configuración estilo Claude Desktop sería:

{
  "mcpServers": {
    "kontomierz": {
      "command": "/absolute/path/to/kontomierz-mcp/.venv/bin/kontomierz-mcp",
      "env": {
        "KONTOMIERZ_API_KEY": "your_api_key_here"
      }
    }
  }
}

Usa el mecanismo de entorno/secreto de confianza de tu cliente cuando esté disponible. No expongas la clave de API a través de argumentos de herramientas. Añade ENABLE_WRITE_OPERATIONS=1 al entorno de proceso de confianza solo cuando se pretendan realizar escrituras.

HTTP Streamable

El modo HTTP es opcional. Está deliberadamente restringido a loopback y requiere autenticación Bearer.

export MCP_TRANSPORT=streamable-http
export MCP_HOST=127.0.0.1
export MCP_PORT=9101
export MCP_HTTP_AUTH_TOKEN="$(.venv/bin/python -c 'import secrets; print(secrets.token_urlsafe(32))')"
export MCP_HTTP_PRINCIPAL=local-operator
export MCP_HTTP_ALLOWED_CAPABILITIES=read

kontomierz-mcp

Endpoints:

Endpoint	Autenticación	Propósito
`POST /mcp`	Token Bearer requerido	Endpoint MCP HTTP Streamable
`GET /health/live`	Público	Solo liveness del proceso; sin E/S ascendente
`GET /health/ready`	Token Bearer requerido	Readiness acotado y consciente de dependencias

Verificar el estado:

curl http://127.0.0.1:9101/health/live
curl -H "Authorization: Bearer $MCP_HTTP_AUTH_TOKEN" \
  http://127.0.0.1:9101/health/ready

Los principales HTTP son de solo lectura por defecto. Para permitir escrituras ordinarias, tanto la política de capacidades HTTP como la puerta de escritura global deben permitirlas:

export MCP_HTTP_ALLOWED_CAPABILITIES=read,write
export ENABLE_WRITE_OPERATIONS=1

Las llamadas HTTP destructivas requieren además destructive más listas de permitidos exactas de capacidades y recursos:

export MCP_HTTP_ALLOWED_CAPABILITIES=read,write,destructive
export MCP_HTTP_ALLOWED_DESTRUCTIVE_CAPABILITIES=destroy_wallet
export MCP_HTTP_ALLOWED_DESTRUCTIVE_RESOURCES=wallet:123
export ENABLE_WRITE_OPERATIONS=1

La autenticación nunca concede acceso de escritura por sí misma.

Docker

El Dockerfile deliberadamente no reconstruye el proyecto desde código fuente arbitrario. Consume la rueda dist/ verificada, el wheelhouse de ejecución, el bloqueo de ejecución, las sumas de verificación y SOURCE_REVISION producidos por la ruta de artefactos exactos, y luego ejecuta el servidor como usuario no root.

Para reproducir la imagen de CI localmente, usa Python 3.12 y el helper del repositorio con un checkout ai-skills en la revisión exacta registrada en trusted-executable-sources.lock.yaml:

.venv/bin/python scripts/local_exact_gate.py --ai-skills-root ../ai-skills

Ese comando ejecuta los controles de estándares/calidad propiedad del repositorio, materializa el conjunto de artefactos exacto y construye kontomierz-mcp:<git-sha>. Consulta Preparación para producción para la ruta reproducible completa.

Para HTTP Streamable dentro de Docker, la publicación ordinaria de -p no es suficiente porque el servidor debe vincularse a loopback. En Linux, usa red de host o un puente de loopback equivalente. Stdio no necesita exposición de red.

Herramientas disponibles (27)

Cuentas

Herramienta	Riesgo	Descripción
`list_accounts`	LECTURA	Lista cuentas bancarias y carteras con saldos
`create_wallet`	ESCRITURA	Crea una cartera de efectivo
`update_wallet`	ESCRITURA	Actualiza una cartera de efectivo
`destroy_wallet`	DESTRUCTIVO	Elimina una cartera de efectivo

Transacciones

Herramienta	Riesgo	Descripción
`list_transactions`	LECTURA	Lista transacciones con paginación y filtros
`get_transaction`	LECTURA	Obtiene una transacción
`create_transaction`	ESCRITURA	Crea una transacción
`update_transaction`	ESCRITURA	Actualiza una transacción
`delete_transaction`	DESTRUCTIVO	Elimina una transacción

Presupuestos

Herramienta	Riesgo	Descripción
`list_budgets`	LECTURA	Lista presupuestos de un mes
`create_budget`	ESCRITURA	Crea un presupuesto de categoría o grupo de categorías
`update_budget`	ESCRITURA	Actualiza un límite de presupuesto
`delete_budget`	DESTRUCTIVO	Elimina un presupuesto
`copy_budgets_from_last_month`	ESCRITURA	Copia los presupuestos del mes anterior

Programaciones

Herramienta	Riesgo	Descripción
`list_scheduled_transactions`	LECTURA	Lista ocurrencias de pagos programados
`get_schedule`	LECTURA	Obtiene una definición de programación
`create_schedule`	ESCRITURA	Crea una programación de pago
`update_schedule`	ESCRITURA	Actualiza una programación de pago
`delete_schedule`	DESTRUCTIVO	Elimina una programación de pago
`mark_schedule_paid`	ESCRITURA	Marca una ocurrencia como pagada
`mark_schedule_unpaid`	ESCRITURA	Marca una ocurrencia como no pagada

Datos de referencia

Herramienta	Riesgo	Descripción
`list_categories`	LECTURA	Lista el árbol de categorías
`list_tags`	LECTURA	Lista etiquetas de usuario
`list_currencies`	LECTURA	Lista monedas

Gráficos y patrimonio

Herramienta	Riesgo	Descripción
`get_pie_chart`	LECTURA	Obtiene datos de desglose de transacciones
`list_wealth_points`	LECTURA	Lista puntos del historial de patrimonio

Introspección

Herramienta	Riesgo	Descripción
`describe_kontomierz_capabilities`	LECTURA	Describe el catálogo de herramientas gobernado y el estado de política activo

El catálogo gobernado en src/kontomierz_mcp/tool_definitions*.py es la fuente de verdad para firmas y descripciones. tools/list expone los esquemas públicos.

Contrato público

La versión 2.0.0 endurece intencionalmente la superficie MCP:

los objetos de entrada de herramientas están cerrados (additionalProperties: false);
los tipos escalares son estrictos en lugar de coerción cruzada;
las fechas públicas usan YYYY-MM-DD y los meses presupuestarios usan YYYY-MM;
la conversión localizada de DD-MM-YYYY de Kontomierz es interna al adaptador;
los metadatos de resultados públicos exponen un target_ref opaco, no la identidad objetivo derivada de credenciales;
los tamaños de respuestas y cuerpos ascendentes están acotados;
los fallos de mutación se clasifican de forma conservadora.

Una creación confirmada con HTTP 201 que no devuelve una identidad estable no se adivina a partir de campos no únicos. Los casos observados de presupuesto/programación devuelven:

{"created": true, "reconciliation_required": true}

El llamador debe conciliar antes de una mutación dependiente. Si la finalización en sí es incierta — por ejemplo, tras un tiempo de espera, pérdida de transporte, fallo ambiguo del servidor o respuesta de mutación exitosa malformada/sobredimensionada — la operación devuelve AMBIGUOUS_OUTCOME y no se reintenta automáticamente.

Consulta Contrato de herramientas y API ascendente para el comportamiento detallado.

Configuración

Toda la configuración se realiza mediante variables de entorno; .env.example es la plantilla completa.

Núcleo

Variable	Predeterminado	Descripción
`KONTOMIERZ_API_KEY`	—	Requerido para el backend real
`KONTOMIERZ_MOCK_DATA`	`0`	Usa datos deterministas en memoria en lugar de Kontomierz
`KONTOMIERZ_API_BASE_URL`	`https://secure.kontomierz.pl/k4`	URL base de la API ascendente; los destinos reales deben ser HTTPS
`KONTOMIERZ_API_TIMEOUT`	`30`	Tiempo de espera de solicitud ascendente en segundos
`KONTOMIERZ_BODY_MODE`	`form`	Las escrituras reales se codifican como formulario; el modo real `json` se rechaza
`MCP_TRANSPORT`	`stdio`	`stdio`, `http` o `streamable-http`
`MCP_HOST`	`127.0.0.1`	Host de enlace HTTP; el HTTP no-loopback se rechaza
`MCP_PORT`	`9101`	Puerto HTTP Streamable
`ENABLE_WRITE_OPERATIONS`	`0`	Puerta de operador independiente para mutaciones
`LOG_LEVEL`	`INFO`	Verbosidad del registro de aplicación

Límites de ejecución

Variable	Predeterminado	Descripción
`MCP_MAX_CONCURRENCY`	`8`	Máximo de llamadas de dependencia en ejecución
`MCP_MAX_PENDING_INVOCATIONS`	`16`	Máximo de invocaciones admitidas en ejecución + en cola
`MCP_READINESS_TIMEOUT`	`5`	Tiempo de espera de la sonda de dependencia de readiness
`MCP_READINESS_CACHE_SECONDS`	`10`	Duración de la caché de readiness
`MCP_HTTP_MAX_REQUEST_BODY_BYTES`	`1048576`	Límite del cuerpo de solicitud HTTP; el máximo absoluto es 4 MiB

Autorización

Variable	Propósito
`MCP_STDIO_ALLOWED_DESTRUCTIVE_CAPABILITIES`	IDs exactos de capacidades destructivas permitidas sobre stdio
`MCP_STDIO_ALLOWED_DESTRUCTIVE_RESOURCES`	IDs exactos de recursos destructivos permitidos sobre stdio
`MCP_HTTP_AUTH_TOKEN`	Token Bearer de alta entropía requerido para HTTP
`MCP_HTTP_PRINCIPAL`	Identidad estable propiedad del servidor mapeada al token HTTP
`MCP_HTTP_ALLOWED_CAPABILITIES`	Clases de capacidades HTTP; predeterminado a `read`
`MCP_HTTP_ALLOWED_DESTRUCTIVE_CAPABILITIES`	IDs exactos de capacidades destructivas permitidas sobre HTTP
`MCP_HTTP_ALLOWED_DESTRUCTIVE_RESOURCES`	IDs exactos de recursos destructivos permitidos sobre HTTP

Seguridad

Solo lectura por defecto. Las escrituras requieren ENABLE_WRITE_OPERATIONS=1; HTTP también requiere la clase de capacidad correspondiente.
Autorización destructiva exacta. Las operaciones destructivas necesitan listas de permitidos explícitas de capacidades y recursos; los recursos con comodines se rechazan.
HTTP solo-loopback. El enlace HTTP remoto se rechaza. /mcp y /health/ready requieren autenticación Bearer.
Identidad propiedad del servidor. Los principales, la identidad objetivo, la política de capacidades, las listas de permitidos de recursos y la habilitación de escritura no pueden provenir de argumentos de herramientas controlados por el modelo.
Sin reintentos automáticos de mutación. Las escrituras con finalización incierta permanecen como AMBIGUOUS_OUTCOME hasta que se concilian.
Datos acotados. Entradas, cuerpos de solicitud, respuestas ascendentes, respuestas de herramientas y eventos de auditoría están acotados.
Auditoría protegida. Los registros de auditoría de invocación excluyen claves de API, tokens Bearer, resultados protegidos sin procesar y argumentos sin procesar.

El proyecto está diseñado para una única cuenta de Kontomierz configurada. No se admiten alojamiento multi-tenant público ni selección de objetivo entre cuentas.

Pruebas y desarrollo

Para desarrollo ordinario:

python -m pip install -e ".[dev]"
python -m pytest
python -m ruff check .
python -m ruff format --check .
python -m mypy src/kontomierz_mcp
python -m bandit -q -r src/kontomierz_mcp

El pytest simple excluye la suite de evidencia external. La cobertura se exige al 85%.

El CI alojado también ejercita los grafos de dependencias Linux x64 bloqueados exactos en Python 3.11, 3.12 y 3.13, clientes MCP oficiales sobre stdio y HTTP Streamable autenticado, instalación de ruedas exactas fuera del árbol de fuentes, y la imagen no root vinculada a revisión.

La suite de mutaciones en vivo de Kontomierz está deliberadamente diseñada para ser difícil de iniciar y solo debe ejecutarse contra una cuenta desechable exclusiva verificada. No la ejecutes contra una cuenta personal normal. Consulta Preparación para producción para sus puertas de seguridad explícitas y requisitos de limpieza.

Estándares y evidencia

El repositorio usa la revisión de autoridad inmutable ai-skills registrada en trusted-executable-sources.lock.yaml para la verificación estructural propiedad del repositorio. Esto prueba qué bytes de verificador ejecutó el CI; no es, por sí mismo, una aprobación respaldada por el proveedor.

El estado formal L2+/adopted está intencionalmente separado del estado de fusión y requiere controles externos del proveedor y evidencia independiente. La evidencia actual y el trabajo administrativo restante están documentados en:

Compatibilidad

La versión 2.0.0 es intencionalmente incompatible con el transporte y el contrato público heredados de la 1.x. En particular, SSE y el puente REST no autenticado han desaparecido, las fechas/meses están canonicalizados, la semántica de paginación es conservadora, la omisión de actualización difiere de una cadena vacía explícita, las operaciones destructivas tienen listas de permitidos exactas, y los metadatos de resultados ya no exponen la identidad interna del objetivo.

Referencia rápida

Métrica	Valor
Versión	2.0.0
Python	3.11+; bloqueos exactos de CI Linux x64 para 3.11–3.13
SDK MCP	`mcp==2.0.0`
Herramientas	27: 12 LECTURA, 11 ESCRITURA, 4 DESTRUCTIVAS
Transportes	stdio; HTTP Streamable de bucle de retorno autenticado
Modo predeterminado	stdio de solo lectura
Licencia	MIT

Licencia

MIT