# money-manager-mcp

CLI + MCP stdio server for querying Realbyte **Money Manager** `.mmbak`
backups (**iPhone and Android**): transaction search, spending summaries and
trends, merchant/recurring analysis, and OCR full-text search over receipt
photos (Traditional Chinese supported). Local-first, read-only against the
backup, no raw SQL exposed to the model.

> **Unofficial project:** this software is not affiliated with, endorsed by,
> or sponsored by Realbyte, the developer of Money Manager.

> The two apps export different databases — iPhone a bare Core Data SQLite
> (`Z*` tables), Android a ZIP-wrapped SQLite (`INOUTCOME`, column names
> varying by app version). The schema is auto-detected and both map onto one
> canonical query layer. Receipt/photo tools are iPhone-only (Android backups
> carry no verified photo table).

## Layout

| File | Purpose |
|---|---|
| [`src/money_manager_search.py`](src/money_manager_search.py) | Single-file CLI + MCP server (installed as the `money-manager` command) |
| [`docs/setup.md`](docs/setup.md) | Setup guide: exporting backups/receipts, MCP config, building the OCR index |
| [`docs/design.md`](docs/design.md) | Full design doc, verified schema findings, deployment + ops runbooks |
| [`docs/roadmap.md`](docs/roadmap.md) | Status, near-term plan (agent deploy, finance-report), candidate features |
| [`skills/`](skills/) | Skill layer: `finance-search` (Q&A answer contract), `finance-sync` (freshness + reindex) |

## Install

Runtime is managed with [uv](https://docs.astral.sh/uv/) (Python 3.12,
pinned in `.python-version`; deps: `mcp`, `rapidocr-onnxruntime`):

```sh
uv sync
```

Without uv (e.g. in the deployment container), the script is stdlib-only for
the CLI: copy `src/money_manager_search.py` anywhere and
`pip install mcp rapidocr-onnxruntime` covers `serve` and OCR.

## Usage

```sh
export MONEY_BACKUP=/path/to/backups   # dir of .mmbak files (newest wins) or one file
export MONEY_PHOTOS=/path/to/receipts  # receipt photo folder (optional, enables OCR tools)
export MONEY_INDEX=/path/to/receipt_index.db

# CLI
uv run money-manager status
uv run money-manager summary -g category -m 2024-01
uv run money-manager search -s "Example Pharmacy" -k expense
uv run money-manager ocr-index            # incremental receipt OCR
uv run money-manager receipt-search -q "green tea"

# MCP server (stdio)
uv run money-manager serve
```

For streamable HTTP, set `MONEY_MCP_TRANSPORT=streamable-http` and a non-empty
`MONEY_MCP_TOKEN`. HTTP mode refuses to start without the token; use HTTPS via
a reverse proxy when traffic leaves a trusted network.

MCP tools: `search`, `summary`, `trends`, `merchants`, `duplicates`,
`compare`, `recurring`, `backup_changes`, `receipts`, `categories`,
`accounts`, `backup_status`, and — when `MONEY_PHOTOS`/`MONEY_INDEX` are
set — `receipt_text_search`, `receipt_text`, `receipt_regex`,
`reindex_receipts`. The server re-resolves the newest `.mmbak` per call,
so fresh uploads need no restart.

## Skills

Agent-agnostic skills live in [`skills/`](skills/) (open Agent Skills format —
a folder per skill with a `SKILL.md`). Install them into any supported agent
(Claude Code, Cursor, Codex, …) with:

```sh
npx skills add <this-repo-url>
```

## Privacy

Backups, receipt photos, and the OCR index contain personal financial history
and are gitignored. Keep them outside the repo; the backup is always opened
read-only (`mode=ro&immutable=1`).

## License

[MIT](LICENSE)