Kontomierz-MCP Server

Kontomierz.pl için MCP (Model Context Protocol) sunucusu — Polonya kişisel finans platformu. AI asistanlarının (Claude Desktop, LibreChat, Cline) tek bir API üzerinden banka hesaplarınızı, işlemlerinizi, bütçelerinizi ve planlı ödemelerinizi okumasını ve yönetmesini sağlar. Python ile geliştirilmiştir, yerel olarak veya Docker'da çalışır.

GitHub

Dokümantasyon

Kontomierz-MCP

MCP (Model Context Protocol) server for Kontomierz.pl — a Polish personal finance platform. Enables AI assistants (Claude Desktop, LibreChat, Cline) to read and manage your bank accounts, transactions, budgets, and scheduled payments — all through a single API. Built in Python, runs locally or in Docker.

Requirements

Python 3.11+ (for local use) or Docker
Kontomierz.pl account with API key

Quick Start

1. Configure

cp .env.example .env
# Edit .env with your KONTOMIERZ_API_KEY

2. Run with Docker

Option A — Build local image:

docker build -t kontomierz-mcp .
docker run -d \
  --name kontomierz-mcp \
  -p 9100:9100 -p 9101:9101 -p 9102:9102 \
  --env-file .env \
  -e MCP_UNSAFE_PUBLIC_ACCESS_CONFIRMED=1 \
  kontomierz-mcp

Option B — From GitHub Container Registry (after publish):

docker run -d \
  --name kontomierz-mcp \
  -p 9100:9100 -p 9101:9101 -p 9102:9102 \
  --env-file .env \
  -e MCP_UNSAFE_PUBLIC_ACCESS_CONFIRMED=1 \
  ghcr.io/paulomac1000/kontomierz-mcp:latest

3. Run locally (Python 3.11+)

pip install -e ".[dev]"
kontomierz-mcp

Ports

Port	Protocol	Purpose	Endpoint
9100	HTTP	Health check	`GET /health`
9101	SSE	MCP transport (SSE)	`/sse`
9102	HTTP	REST API bridge	`/api/*`

Verify

# Health check
curl http://localhost:9100/health

# List all 27 MCP tools
curl http://localhost:9102/api/tools

# Call a tool via REST API
curl -X POST http://localhost:9102/api/tools/list_accounts \
  -H "Content-Type: application/json" \
  -d '{"params":{}}'

# Get tool capability manifest
curl http://localhost:9102/api/tools/list_tags/manifest

Available Tools (27)

Accounts

Tool	Risk	Description
`list_accounts`	[READ]	List all bank accounts and wallets with balances
`create_wallet`	[WRITE]	Create a new cash wallet
`update_wallet`	[WRITE]	Update a cash wallet
`destroy_wallet`	[DESTRUCTIVE]	Delete a cash wallet

Transactions

Tool	Risk	Description
`list_transactions`	[READ]	List money transactions with pagination and filters
`get_transaction`	[READ]	Get details of a single transaction
`create_transaction`	[WRITE]	Create a new transaction in a wallet
`update_transaction`	[WRITE]	Update an existing transaction
`delete_transaction`	[DESTRUCTIVE]	Delete a transaction

Budgets

Tool	Risk	Description
`list_budgets`	[READ]	List budgets for a given month
`create_budget`	[WRITE]	Create a budget for a category or group
`update_budget`	[WRITE]	Update a budget limit
`delete_budget`	[DESTRUCTIVE]	Delete a budget
`copy_budgets_from_last_month`	[WRITE]	Copy last month's budgets to current month

Schedules

Tool	Risk	Description
`list_scheduled_transactions`	[READ]	List scheduled payments (unpaid/paid) with pagination
`get_schedule`	[READ]	Get details of a payment schedule
`create_schedule`	[WRITE]	Create a new payment schedule
`update_schedule`	[WRITE]	Update a payment schedule
`delete_schedule`	[DESTRUCTIVE]	Delete a payment schedule
`mark_schedule_paid`	[WRITE]	Mark a scheduled payment as paid
`mark_schedule_unpaid`	[WRITE]	Mark a scheduled payment as unpaid

Reference

Tool	Risk	Description
`list_categories`	[READ]	List category tree (withdrawal/deposit)
`list_tags`	[READ]	List user tags sorted by recent usage
`list_currencies`	[READ]	List currency dictionary (major/minor/trivial)

Charts & Wealth

Tool	Risk	Description
`get_pie_chart`	[READ]	Get pie chart data for transaction breakdown
`list_wealth_points`	[READ]	List net worth history points

Introspection

Tool	Risk	Description
`describe_kontomierz_capabilities`	[READ]	Return full tool catalog with manifests and schema version

Configuration

All configuration is via environment variables. See .env.example for a complete template.

Required

Variable	Description	Example
`KONTOMIERZ_API_KEY`	API key from kontomierz.pl/profil/api	`hz4Z8NY...`

Optional

Variable	Default	Description
`MCP_PORT`	`9101`	MCP SSE transport port
`REST_API_PORT`	`9102`	REST API bridge port
`HEALTH_PORT`	`9100`	Health check HTTP port
`LOG_LEVEL`	`INFO`	DEBUG, INFO, WARNING, ERROR, CRITICAL
`ENABLE_WRITE_OPERATIONS`	`false`	Set to `1`/`true`/`yes`/`on` to enable write/destructive tools
`MCP_UNSAFE_PUBLIC_ACCESS_CONFIRMED`	—	Set to `1` for Docker port forwarding (binds to `0.0.0.0`)
`KONTOMIERZ_API_TIMEOUT`	`30`	API request timeout in seconds

REST API

The REST API on port 9102 provides HTTP access to all tools, health checks, and tool manifests.

# List tools
curl http://localhost:9102/api/tools

# Get tool manifest
curl http://localhost:9102/api/tools/create_wallet/manifest

# Invoke a tool
curl -X POST http://localhost:9102/api/tools/list_transactions \
  -H "Content-Type: application/json" \
  -d '{"params":{"page":"1","start_on":"01-05-2026"}}'

Security

Read-only by default — ENABLE_WRITE_OPERATIONS=false. All write/destructive tools return AUTH_FAILED until explicitly enabled.
Structured errors — every error includes code, message, and retryable fields so AI agents can branch programmatically.
Credential protection — API key is never logged or returned in responses. Log formatter sanitizes Bearer tokens, API keys, and IP addresses.
Response sanitization — response payloads are recursively sanitized before being sent to AI clients.
Localhost binding — all ports bind to 127.0.0.1 by default. Set MCP_UNSAFE_PUBLIC_ACCESS_CONFIRMED=1 for Docker.

Standards Compliance

Standard	Document	Level	Description
MCP Core	`mcp-server-standards.md`	L2+	Tool design, response contracts, testing hierarchy, security
CI/CD	`ci-cd-standard.md`	v2.0.0	Workflows, quality gates, security scanning, dependency management

Compliance level: L2+ (Tool Manifests, structured errors, write guard, three-port, SanitizingFormatter, Risk Consistency Matrix, cleanup tests, Semgrep + Dependabot).

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "kontomierz": {
      "url": "http://localhost:9101/sse"
    }
  }
}

Testing

pip install -e ".[dev]"

# Unit tests (zero I/O, fast, 150 tests)
pytest tests/unit/ -q

# Integration tests (mocked client, full pipeline, 19 tests)
pytest tests/integration/ -q

# Coverage (unit + integration, requires ≥80%)
pytest tests/unit/ tests/integration/ --cov=kontomierz_mcp --cov-report=term

# Smoke tests (requires running server on port 9102)
pytest tests/smoke/ -q

# E2E tests (requires running server on port 9102)
pytest tests/e2e/ -q

# Lint, type check, security
ruff check . && ruff format --check .
mypy src/kontomierz_mcp/
bandit -c pyproject.toml -r src/ -ll

Quick Reference

Metric	Value
Python	3.11+ (CI: 3.14)
Tools	27 (14 READ + 10 WRITE + 3 DESTRUCTIVE)
Tests	169 (150 unit + 19 integration)
Coverage	91%
Lint	0 errors (ruff + mypy + bandit)
Docker	`ghcr.io/paulomac1000/kontomierz-mcp:latest`
Standards	MCP Core L2+ + CI/CD v2.0.0
License	MIT