Kontomierz-MCP

Version2.0.0replaces the old SSE/REST bridge withstdioand authenticated, loopback-onlyStreamable HTTP. Public dates are ISOYYYY-MM-DD, budget months areYYYY-MM, and write operations are disabled unless the server operator explicitly enables them.

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.envfrom 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 gateandexact 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. AddENABLE_WRITE_OPERATIONS=1to 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 requiredestructiveplus 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 doesnotrebuild the project from arbitrary source. It consumes the verifieddist/wheel, runtime wheelhouse, runtime lock, checksums, andSOURCE_REVISIONproduced 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 anai-skillscheckout at the exact revision recorded intrusted-executable-sources.lock.yaml:

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

For Streamable HTTP inside Docker, ordinary-ppublishing 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 insrc/kontomierz_mcp/tool_definitions*.pyis the source of truth for signatures and descriptions.tools/listexposes 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 useYYYY-MM-DDand budget months useYYYY-MM;
- localized KontomierzDD-MM-YYYYconversion is adapter-internal;
- public result metadata exposes an opaquetarget_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 returnsAMBIGUOUS_OUTCOMEand is not automatically retried.

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

- Read-only by default.Writes requireENABLE_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./mcpand/health/readyrequire 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 remainAMBIGUOUS_OUTCOMEuntil 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.

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

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.