mmex-mcp

A read-only Model Context Protocol server for Money Manager EX. Point it at your .mmb file and ask an assistant about your finances.

It never writes to your database and never opens a network socket.

Install

Not published to npm yet, so build it from a clone:

git clone https://github.com/EriWinckler/mmex-mcp && cd mmex-mcp
npm install && npm run build

Register it with Claude Code:

claude mcp add mmex -- node "$PWD/dist/bin/server.js" --db ~/finances.mmb

Once published that becomes claude mcp add mmex -- npx -y mmex-mcp --db ~/finances.mmb.

Try it without your own data

node dist/bin/fixture.js --out demo.mmb
claude mcp add mmex-demo -- node "$PWD/dist/bin/server.js" --db "$PWD/demo.mmb"

That writes a synthetic database with fabricated accounts, payees and 18 months of transactions. Remove it with claude mcp remove mmex-demo.

Related MCP server: OpenCoffer

Options

--db <file>      Path to the MMEX database
--config <file>  Config file (default ./mmex-mcp.config.json, then ~/.config/mmex-mcp/config.json)
--snapshot       Read a temporary copy, for when Money Manager EX is running and holding the file
--redact         Replace payee, account and category names with stable placeholders; amounts unchanged

Environment equivalents: MMEX_MCP_DB, MMEX_MCP_SNAPSHOT, MMEX_MCP_REDACT. Flags beat environment beats config file. Set MMEX_MCP_LOG=debug for diagnostics on stderr.

Full details in docs/CLAUDE_CODE.md.

Tools

Every tool returns exact decimal amounts in your base currency, plus a basis block saying how the figure was produced: which rate date was used, and what was excluded. When a number disagrees with a Money Manager EX report, that block plus docs/CONFORMANCE.md is the explanation.

Status

Early. The foundation is built and tested; the analytics surface is not.

148 tests. Typecheck and lint clean.

Why the queries are not obvious

The reason this is a semantic layer rather than a SQL passthrough is that the MMEX schema has five traps, and a plausible-looking query falls into all of them:

Amounts are stored in numeric columns, which SQLite returns as floats: SELECT 10.10 + 20.20 gives 30.299999999999997. This server converts to integer minor units at the SQL boundary and formats back only at output.

Which semantics

MMEX's two published general reports disagree with each other, so they cannot serve as the specification:

This server follows the desktop application instead, read from its C++ source (1.9.4 RC1, commit 35f3081), with a file and line citation for each rule. The comparison surfaced eight divergences from the published reports, including two that lose data: ExpenseAndRevenueByMonth ignores DELETEDTIME entirely, and CategoriesStatLast12Months drops uncategorized non-split transactions rather than bucketing them.

All eight are in docs/CONFORMANCE.md, which is the answer to "why does your number differ from my report".

Safety

• Read-only, enforced by readonly: true at the SQLite handle and PRAGMA query_only = ON at the SQL layer.

• mmex_database_info reports the live posture by attempting a write (DELETE ... WHERE 1 = 0, a no-op even if permitted) and returning the SQLite error code that refused it.

• No network access. The server opens no sockets.

• The database path is never exposed. It contains your account name and would otherwise land in transcripts, screen shares and pasted bug reports. This is privacy hygiene, not an access control: an assistant with shell access can still find the file via ps, the client config, or find. The defense against a raw query is that it gives wrong answers, which is what the semantic layer and the conformance document are for.

• --redact for screen sharing; --snapshot to avoid touching a live file.

• API keys are read only from named environment variables, never from a config file; an inline key is rejected with an error.

• .gitignore refuses *.mmb and *.emb.

• Three direct dependencies, 97 transitive, mostly from the MCP SDK's bundled HTTP transport that this stdio server does not use.

Threat model and limits: SECURITY.md.

Development

Node 22+ (24 LTS recommended).

npm install
npm run verify     # typecheck, lint, test
npm run build

Architecture and design decisions: docs/ARCHITECTURE.md. Contributing: CONTRIBUTING.md.

Roadmap

• An answer-accuracy regression suite: unit tests prove the SQL is right, but not that an assistant given these tools answers correctly. Running the same questions against raw SQL is the control, showing which semantic rules are load-bearing.

• Encrypted .emb (SQLCipher) support.

• Optional write mode behind a flag, with dry-run and backup.

Related

Personal finance MCP servers exist for MoneyWiz, Monarch Money and others. None targets Money Manager EX.

License

MIT, see LICENSE. Money Manager EX is GPL-2.0 and unaffiliated; the schema definitions here are written from the documented table and column names rather than copied from upstream.