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. - 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](https://kontomierz.pl/)[API key, unless using the deterministic mock backend. - Docker only if you want to reproduce or run the exact container artifact. ``` `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: Stdio is the default and recommended transport for a local MCP client: 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. 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. 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` ``` ``` `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. 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:<git-sha>`. See](https://kontomierz.pl/profil/api)[Production readinessfor 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. 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. 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](https://github.com/paulomac1000/kontomierz-mcp/blob/HEAD/docs/production-readiness.md)[Tool contractand](https://github.com/paulomac1000/kontomierz-mcp/blob/HEAD/docs/tool-contract.md)[Upstream APIfor the detailed behavior. All configuration is via environment variables;`.env.example`is the complete template. - **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. ``` `python -m pip install -e ".](https://github.com/paulomac1000/kontomierz-mcp/blob/HEAD/docs/upstream-api.md)[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 readinessfor its explicit safety gates and cleanup requirements. The repository uses the immutable`ai-skills`authority revision recorded in](https://github.com/paulomac1000/kontomierz-mcp/blob/HEAD/docs/production-readiness.md)[`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: - ](https://github.com/paulomac1000/kontomierz-mcp/blob/HEAD/trusted-executable-sources.lock.yaml)[AI Skills gap assessment - ](https://github.com/paulomac1000/kontomierz-mcp/blob/HEAD/docs/ai-skills-gap-assessment.md)[Production readiness - ](https://github.com/paulomac1000/kontomierz-mcp/blob/HEAD/docs/production-readiness.md)[System architecture - ](https://github.com/paulomac1000/kontomierz-mcp/blob/HEAD/docs/system-architecture.md)[Tool contract - ](https://github.com/paulomac1000/kontomierz-mcp/blob/HEAD/docs/tool-contract.md)[Upstream API - ](https://github.com/paulomac1000/kontomierz-mcp/blob/HEAD/docs/upstream-api.md)[`upstream-contract.yaml` - ](https://github.com/paulomac1000/kontomierz-mcp/blob/HEAD/upstream-contract.yaml)[`live-backend-test-policy.yaml` 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. Funding rounds, acquisitions & exec moves — deduped, enriched, typed. Query over REST, stream over webhooks, or hand to your agent over MCP. 50 free credits. Brazilian Open Finance MCP — connect 30+ banks (Itaú, Nubank, Bradesco, Santander, Inter, BB, Caixa, C6 and more) to Claude/Cursor. 13 read-only tools. Live MCP server connecting AI agents to 36+ business data sources. OAuth 2.1 PKCE. US stock market & financial data — SEC filings full-text search, XBRL fundamentals, 13F institutional holdings, insider & congressional trades, earnings-call transcripts, short interest, and FRED macro; 90+ tools, free tier, self-hostable. A Model Context Protocol (MCP) server that exposes the FINRA Query API as a set of tools. Get financial data and details about Romanian companies straight from ONRC and ANAF Access BIST and global market data directly Macroeconomic and FX data API + MCP server for 18 currencies with central bank announcements, calendar, COT, commodities, and forex. Log, query, and edit expenses, budgets, and accounts from Claude, ChatGPT, Cursor, or any MCP-compatible AI assistant — the only expense tracker with a native MCP server. Company, KYB, VAT, sanctions, LEI and address data for 15 EU countries (DK, NO, SE, FI, IE, UK, FR, DE, CZ, PL, LV, EE, NL, BE, LU). Free tier 100 lookups/day at addonnordic.com.](https://github.com/paulomac1000/kontomierz-mcp/blob/HEAD/live-backend-test-policy.yaml)