ZenMoney MCP Server
An MCP (Model Context Protocol) server for integrating Claude with ZenMoney — a personal finance tracking app.
Features
- View accounts and balances
- Search and filter transactions
- Create, update, and delete transactions
- Browse the category tree and budgets
- Category suggestions by payee name
Quick Start (uvx)
The easiest way to run the server is with uvx — no cloning or manual installation needed. Requires uv to be installed.
Add the server to Claude Desktop (Settings → Developer → Edit Config):```json
{
"mcpServers": {
"zenmoney": {
"command": "uvx",
"args": ["--from", "git+https://github.com/germanKoch/zenmoney-mcp", "zenmoney-mcp"]
}
}
}
Or add it to Claude Code:```bash
claude mcp add zenmoney -- uvx --from git+https://github.com/germanKoch/zenmoney-mcp zenmoney-mcp
Provide an existing access token or configure OAuth application credentials as
described below. With application credentials configured, first use opens the
ZenMoney login page. The resulting token is saved locally and refreshed automatically.
Authorization
The server resolves credentials in the following priority order:
1. Environment variables
Pass token data directly via the environment — useful for headless setups or when you already have a token (e.g. from zerro.app/token):
| Variable | Description |
|---|---|
ZENMONEY_ACCESS_TOKEN |
OAuth access token (alias: ZENMONEY_TOKEN) |
ZENMONEY_REFRESH_TOKEN |
OAuth refresh token — lets the server refresh the access token when it expires |
ZENMONEY_TOKEN_TYPE |
Token type (usually bearer) |
ZENMONEY_EXPIRES_IN |
Token lifetime in seconds |
ZENMONEY_CLIENT_ID |
OAuth application ID, required for browser login and refresh |
ZENMONEY_CLIENT_SECRET |
OAuth application secret, required for browser login and refresh |
{
"mcpServers": {
"zenmoney": {
"command": "uvx",
"args": ["--from", "git+https://github.com/germanKoch/zenmoney-mcp", "zenmoney-mcp"],
"env": {
"ZENMONEY_ACCESS_TOKEN": "your_access_token",
"ZENMONEY_REFRESH_TOKEN": "your_refresh_token",
"ZENMONEY_TOKEN_TYPE": "bearer",
"ZENMONEY_EXPIRES_IN": "86400"
}
}
}
}
If only ZENMONEY_ACCESS_TOKEN is set, the token is used as-is until it expires.
Refreshing requires both a refresh token and the credentials of the application
that issued the grant.
2. Saved token file
Tokens obtained via OAuth (or refreshed) are stored in ~/.config/zenmoney-mcp/token.json. Override the location with the ZENMONEY_TOKEN_FILE environment variable.
Application credentials can be supplied as client_id and client_secret in
the token JSON, through the environment variables above, or in a separate
~/.config/zenmoney-mcp/oauth-client.json file:```json
{"client_id": "your_app_id", "client_secret": "your_app_secret"}
Set `ZENMONEY_CLIENT_FILE` to use another credentials file. Token JSON takes
precedence over environment variables, followed by this file. Keep credential
files outside the repository and readable only by your user. No application
credentials are bundled with the server.```sh
chmod 600 ~/.config/zenmoney-mcp/oauth-client.json
3. Browser OAuth flow (automatic)
If no valid token is found and application credentials are configured, the server:
- Starts a local HTTP server on port
3000 - Opens a browser with the ZenMoney login page
- Exchanges the authorization code for a token after you sign in
- Saves the token and refreshes it automatically when it expires
Running from source```bash
git clone https://github.com/germanKoch/zenmoney-mcp.git
cd zenmoney-mcp
uv sync
uv run zenmoney-mcp
Claude Desktop config for a local checkout:```json
{
"mcpServers": {
"zenmoney": {
"command": "uv",
"args": ["run", "--directory", "/absolute/path/to/zenmoney-mcp", "zenmoney-mcp"]
}
}
}
Cloudflare Workers
An optional Cloudflare Workers adapter exposes the same
tools over authenticated Streamable HTTP, with persistent account state and
automatic token refresh. The local stdio setup above continues to work.
Available tools
| Tool | Description |
|---|---|
get_accounts |
List accounts with balances |
get_transactions |
Transactions filtered by date, account, or category |
create_transaction |
Create an expense, income, or transfer |
update_transaction |
Update an existing transaction |
delete_transaction |
Delete a transaction |
get_categories |
Category tree |
get_budgets |
Budgets per category for a period |
suggest_category |
Category suggestion by payee name |
Example prompts
- "Show my accounts and balances"
- "What did I spend last week?"
- "Record a 500 RUB grocery expense from my Tinkoff card"
- "How much did I spend on cafes in January?"
