Kontomierz-MCP

MCP (Model Context Protocol) server for Kontomierz.pl — a Polish personal-finance platform. It exposes 27 tools for accounts, transactions, budgets, scheduled payments, reference data, charts, and wealth history so MCP-compatible assistants can work with Kontomierz through one local server.

Version 2.0.0 replaces the old SSE/REST bridge with stdio and authenticated, loopback-only Streamable HTTP. Public dates are ISO `YYYY-MM-DD`, budget months are `YYYY-MM`, and write operations are disabled unless the server operator explicitly enables them.

Requirements

• Python 3.11+ for local use. The repository's exact Linux x64 dependency locks cover Python 3.11, 3.12, and 3.13.
• A Kontomierz.pl account with an API key, unless using the deterministic mock backend.
• Docker only if you want to reproduce or run the exact container artifact.

Quick Start

1. Install and configure

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

The server reads `.env` from the current working directory without overriding variables already present in the process environment.

For a zero-I/O local demo, no real API key is needed:

KONTOMIERZ_MOCK_DATA=1 kontomierz-mcp

2. Run with stdio

Stdio is the default and recommended transport for a local MCP client:

kontomierz-mcp

Read tools are available immediately. Ordinary writes require the independent operator gate:

export ENABLE_WRITE_OPERATIONS=1
kontomierz-mcp

Destructive tools require the write gate and exact server-owned capability/resource allowlists. For example:

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

Wildcards are not accepted for destructive resources.

3. Connect an MCP client

A stdio client can start the executable directly. For example, a Claude Desktop-style configuration is:

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

Use your client's trusted environment/secret mechanism where available. Do not expose the API key through tool arguments. Add `ENABLE_WRITE_OPERATIONS=1` to the trusted process environment only when writes are intended.

Streamable HTTP

HTTP mode is optional. It is deliberately restricted to loopback and requires Bearer authentication.

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:

Verify health:

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

HTTP principals are read-only by default. To allow ordinary writes, both the HTTP capability policy and the global write gate must allow them:

export MCP_HTTP_ALLOWED_CAPABILITIES=read,write
export ENABLE_WRITE_OPERATIONS=1

Destructive HTTP calls additionally require `destructive` plus exact capability and resource allowlists:

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

Authentication never grants write access by itself.

Docker

The Dockerfile intentionally does not rebuild the project from arbitrary source. It consumes the verified `dist/` wheel, runtime wheelhouse, runtime lock, checksums, and `SOURCE_REVISION` produced by the exact-artifact path, then runs the server as a non-root user.

To reproduce the CI image locally, use Python 3.12 and the repository helper with an `ai-skills` checkout at the exact revision recorded in `trusted-executable-sources.lock.yaml`:

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

That command runs the repository-owned standards/quality checks, materializes the exact artifact set, and builds `kontomierz-mcp:`. See Production readiness for the complete reproducible path.

For Streamable HTTP inside Docker, ordinary `-p` publishing is not sufficient because the server is required to bind loopback. On Linux, use host networking or an equivalent loopback bridge. Stdio needs no network exposure.

Available Tools (27)

Accounts

Transactions

Budgets

Schedules

Reference data

Charts & wealth

Introspection

The governed catalog in `src/kontomierz_mcp/tool_definitions*.py` is the source of truth for signatures and descriptions. `tools/list` exposes the public schemas.

Public Contract

Version 2.0.0 intentionally tightens the MCP surface:

• tool input objects are closed (`additionalProperties: false`);
• scalar types are strict rather than cross-coerced;
• public dates use `YYYY-MM-DD` and budget months use `YYYY-MM`;
• localized Kontomierz `DD-MM-YYYY` conversion is adapter-internal;
• public result metadata exposes an opaque `target_ref`, not the internal credential-derived target identity;
• response and upstream-body sizes are bounded;
• mutation failures are classified conservatively.

A confirmed HTTP 201 create that returns no stable identity is not guessed from non-unique fields. Observed budget/schedule cases return:

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

The caller must reconcile before a dependent mutation. If completion itself is uncertain — for example after a timeout, transport loss, ambiguous server failure, or malformed/oversized successful mutation response — the operation returns `AMBIGUOUS_OUTCOME` and is not automatically retried.

See Tool contract and Upstream API for the detailed behavior.

Configuration

All configuration is via environment variables; `.env.example` is the complete template.

Core

Runtime bounds

Authorization

Security

• Read-only by default. Writes require `ENABLE_WRITE_OPERATIONS=1`; HTTP also requires the corresponding capability class.
• Exact destructive authorization. Destructive operations need explicit capability and resource allowlists; wildcard resources are rejected.
• Loopback-only HTTP. Remote HTTP binding is rejected. `/mcp` and `/health/ready` require Bearer authentication.
• Server-owned identity. Principals, target identity, capability policy, resource allowlists, and write enablement cannot come from model-controlled tool arguments.
• No automatic mutation retries. Completion-uncertain writes remain `AMBIGUOUS_OUTCOME` until reconciled.
• Bounded data. Inputs, request bodies, upstream responses, tool responses, and audit events are bounded.
• Protected audit. Invocation audit records exclude API keys, Bearer tokens, raw protected results, and raw arguments.

The project is designed for a single configured Kontomierz account. Public multi-tenant hosting and cross-account target selection are not supported.

Testing and Development

For ordinary development:

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

Plain `pytest` excludes the `external` evidence suite. Coverage is enforced at 85%.

Hosted CI also exercises the exact locked Linux x64 dependency graphs on Python 3.11, 3.12, and 3.13, official MCP clients over stdio and authenticated Streamable HTTP, exact-wheel installation outside the source tree, and the non-root revision-bound image.

The live Kontomierz mutation suite is deliberately hard to start and must only run against a verified exclusive disposable account. Do not run it against a normal personal account. See Production readiness for its explicit safety gates and cleanup requirements.

Standards and Evidence

The repository uses the immutable `ai-skills` authority revision recorded in `trusted-executable-sources.lock.yaml` for repository-owned structural verification. That proves which verifier bytes CI executed; it is not, by itself, provider-backed approval.

Formal L2+/`adopted` status is intentionally separate from merge status and requires external provider controls and independent evidence. The current evidence and remaining administrative work are documented in:

• AI Skills gap assessment
• Production readiness
• System architecture
• Tool contract
• Upstream API
• `upstream-contract.yaml`
• `live-backend-test-policy.yaml`

Compatibility

Version 2.0.0 is intentionally incompatible with the legacy 1.x transport and public contract. In particular, SSE and the unauthenticated REST bridge are gone, dates/months are canonicalized, pagination semantics are conservative, update omission differs from an explicit empty string, destructive operations have exact allowlists, and result metadata no longer exposes internal target identity.

Quick Reference

License

MIT