Metadata-Version: 2.4
Name: moneymanager-mcp
Version: 0.3.0
Summary: MCP stdio server for Realbyte Money Manager .mmbak backups.
Project-URL: Homepage, https://github.com/shubham1172/moneymanager-mcp
Project-URL: Repository, https://github.com/shubham1172/moneymanager-mcp
Project-URL: Issues, https://github.com/shubham1172/moneymanager-mcp/issues
Author-email: Shubham Sharma <shubhamsharma1172@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: finance,mcp,mmbak,money-manager,realbyte
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: mcp>=1.2
Requires-Dist: moneymanager-parser>=0.3
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.2; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# moneymanager-mcp

[![CI](https://github.com/shubham1172/moneymanager-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/shubham1172/moneymanager-mcp/actions/workflows/ci.yml)
![PyPI](https://img.shields.io/badge/PyPI-unpublished-lightgrey)

MCP stdio server for querying Realbyte Money Manager `.mmbak` exports with AI clients.

The server reads a local `.mmbak` file, which is a ZIP-wrapped SQLite database, through the
`moneymanager-parser` SDK. It exposes tools for filtered queries, schema inspection, category
listing, accounts (names and balances), and currencies. Query top/list rows include
`account` and `to_account` for each transaction.

## Install

```bash
pip install moneymanager-mcp
```

## Run

Point the server at a backup file with `MONEY_BACKUP` or pass `backup_path` to each tool:

```bash
export MONEY_BACKUP=/path/to/backup.mmbak
moneymanager-mcp
```

Tools:

- `query(backup_path=None, date_from=None, date_to=None, month=None, category=None, search=None, kind="expense", group_by=None, top=None, list_n=None, limit=24)`
- `schema(backup_path=None)`
- `list_categories(backup_path=None)`
- `accounts(backup_path=None)`
- `currency(backup_path=None)`

Invalid or missing backups return a JSON error payload instead of crashing the server.

## Client configuration

These clients launch `moneymanager-mcp` as a local stdio server, so the command must be on your
`PATH`. Installing with [pipx](https://pipx.pypa.io) keeps it isolated and globally available:

```bash
pipx install moneymanager-mcp
# or: pip install --user moneymanager-mcp
```

Point the server at your backup with the `MONEY_BACKUP` environment variable (shown below), or omit
it and pass `backup_path` to each tool call.

### GitHub Copilot CLI

Option A — interactive: start `copilot`, run the `/mcp` slash command, choose **Add server**, and
enter the command `moneymanager-mcp` with the `MONEY_BACKUP` environment variable.

Option B — config file: add the server to `~/.copilot/mcp-config.json`:

```json
{
  "mcpServers": {
    "money-manager": {
      "type": "local",
      "command": "moneymanager-mcp",
      "args": [],
      "tools": ["*"],
      "env": { "MONEY_BACKUP": "/path/to/backup.mmbak" }
    }
  }
}
```

Restart `copilot`, then run `/mcp` to confirm the server and its tools are listed.

### VS Code (GitHub Copilot agent mode)

Create `.vscode/mcp.json` in your workspace (or run **MCP: Add Server** from the Command Palette and
pick **Workspace**):

```json
{
  "servers": {
    "money-manager": {
      "type": "stdio",
      "command": "moneymanager-mcp",
      "args": [],
      "env": { "MONEY_BACKUP": "/path/to/backup.mmbak" }
    }
  }
}
```

Open the Chat view, switch to **Agent** mode, and select the tools via **Configure Tools**. Use
**MCP: Open User Configuration** instead if you want the server available across all workspaces.

### Claude Desktop

Open **Settings → Developer → Edit Config** (or edit the file directly) and add the server. The config
file is at `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS and
`%APPDATA%\Claude\claude_desktop_config.json` on Windows:

```json
{
  "mcpServers": {
    "money-manager": {
      "command": "moneymanager-mcp",
      "env": { "MONEY_BACKUP": "/path/to/backup.mmbak" }
    }
  }
}
```

Restart Claude Desktop; the Money Manager tools then appear in the tools menu.

> Tip: if a client cannot find `moneymanager-mcp`, use the absolute path to the executable (find it
> with `which moneymanager-mcp`) as the `command` value.

## Development

```bash
python3 -m venv .venv
. .venv/bin/activate
pip install -e '.[dev]'
ruff check .
ruff format --check .
mypy src
pytest --cov
```

## Contributing

Issues and pull requests are welcome. Please use generated sample backups in tests rather than
personal exports.

## License

MIT © 2026 Shubham Sharma
