Name: Kontomierz-MCP
Author: paulomac1000

LABSCO SUMMARY

Deleting a wallet takes two gates and the wallet's own id.

Personal finance data is exactly where a confused agent should not be able to improvise, and this is unusually strict about it: the write gate alone is not enough for a destructive call, and the allowlist has to name the resource. describe_kontomierz_capabilities is how you find out what is currently permitted rather than guessing from the error.

What it is

A local MCP server for Kontomierz.pl, a Polish personal-finance platform. Version 2.0.0 replaced the older SSE/REST bridge with stdio plus an authenticated, loopback-only Streamable HTTP mode, and put every mutation behind an operator gate.

What you get

Accounts — list_accounts with balances, plus create_wallet, update_wallet and the destructive destroy_wallet
Transactions — list_transactions with pagination and filters, get_transaction, create_transaction, update_transaction, delete_transaction
Budgets — list_budgets for a month, create_budget, update_budget, delete_budget, copy_budgets_from_last_month
Schedules — list_scheduled_transactions, get_schedule, create_schedule, update_schedule, delete_schedule, mark_schedule_paid, mark_schedule_unpaid
Reference data — list_categories, list_tags, list_currencies
Charts and wealth — get_pie_chart for a transaction breakdown, list_wealth_points for wealth history
describe_kontomierz_capabilities — the governed tool catalog and the policy currently in force
Every tool is labelled READ, WRITE or DESTRUCTIVE, and public dates are ISO YYYY-MM-DD with budget months as YYYY-MM

Requirements

Python 3.11+ and a Kontomierz.pl account with an API key, set as KONTOMIERZ_API_KEY — or KONTOMIERZ_MOCK_DATA=1 for a deterministic local demo with no key at all. Read tools work immediately. Ordinary writes need ENABLE_WRITE_OPERATIONS=1 in the trusted process environment. Destructive tools additionally need exact allowlists — MCP_STDIO_ALLOWED_DESTRUCTIVE_CAPABILITIES and MCP_STDIO_ALLOWED_DESTRUCTIVE_RESOURCES, naming the capability and the specific resource such as wallet:123; wildcards are refused. HTTP mode is optional, restricted to loopback, and requires a Bearer token via MCP_HTTP_AUTH_TOKEN; HTTP principals are read-only until MCP_HTTP_ALLOWED_CAPABILITIES says otherwise.

Setup effort

Build from source — git clone https://github.com/paulomac1000/kontomierz-mcp.git

See installation options

USE CASES

01

Seeing where the money went this month

List transactions with filters and read the breakdown as a chart.

list_transactionsget_pie_chartlist_categories

02

Setting up next month's budgets

Copy last month's forward, then adjust the limits that need changing.

copy_budgets_from_last_monthlist_budgetsupdate_budget

03

Keeping on top of recurring payments

List the upcoming occurrences and mark them paid as they clear.

list_scheduled_transactionsmark_schedule_paid

04

Trying it before connecting real accounts

Run against the deterministic mock backend with no API key.

list_accountsdescribe_kontomierz_capabilities

27 tools

Listed in project docs. Your client may show a different list.

list_accounts

create_wallet

update_wallet

destroy_wallet

list_transactions

get_transaction

create_transaction

update_transaction

delete_transaction

list_budgets

create_budget

update_budget

delete_budget

copy_budgets_from_last_month

list_scheduled_transactions

BEFORE YOU INSTALL

What to know first

Tools you get

27 tools named in the project's documentation. Write tools are disabled unless ENABLE_WRITE_OPERATIONS=1, leaving the twelve read tools. Destructive tools also need a per-resource allowlist, and MCP_HTTP_ALLOWED_CAPABILITIES can narrow HTTP mode.

Requires

Python 3.11+
KONTOMIERZ_API_KEY in your environment

Where it runs

The documented client runs the server on your machine.

INSTALLATION

Connect your client

You clone this one yourself.

Server setup

TERMINAL

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

kontomierz-mcp (stdio, read-only by default; KONTOMIERZ_MOCK_DATA=1 kontomierz-mcp for a keyless demo)

MCP Clients

Claude Desktop

CLAUDE DESKTOP · JSON

{
  "mcpServers": {
    "kontomierz": {
      "command": "<YOUR_PATH_TO_KONTOMIERZ_MCP>/.venv/bin/kontomierz-mcp",
      "env": {
        "KONTOMIERZ_API_KEY": "<YOUR_KONTOMIERZ_API_KEY>"
      }
    }
  }
}

Kontomierz-MCP