# finanze-mcp

An [MCP](https://modelcontextprotocol.io) server for [Finanze](https://github.com/finanze/finanze),
the self-hosted portfolio manager.

It lets an AI assistant (Claude Code, Claude Desktop…) read your Finanze portfolio and run
financial calculations in plain language — *"what's my net worth?"*, *"show my crypto
positions"*, *"simulate this mortgage"*.

It talks to your local Finanze backend over its HTTP API and exposes a **read-only** tool set
(plus optional live-refresh). It never changes your data.

## What it can do

- **See your portfolio:** positions, contributions, transactions, net-worth timeline, history.
- **Markets:** exchange & Euribor rates, stock/fund/ETF lookup, crypto asset search.
- **Real estate & cash flows:** properties, recurring and pending flows.
- **Calculations:** loan/mortgage amortization, savings projections, portfolio forecast.
- **Optional live refresh** (off by default): trigger a data fetch from your connected banks,
  brokers and crypto wallets.

## Requirements

- A running [Finanze](https://github.com/finanze/finanze) backend (default `http://localhost:7592`).
- Python 3.11+.

## Install

```bash
git clone https://github.com/adriadam10/finanze-mcp.git
cd finanze-mcp
pip install -e .
```

## Configure

Copy the example env file and fill in your Finanze credentials (used to unlock the local DB):

```bash
cp .env.example .env
```

```ini
FINANZE_BASE_URL=http://localhost:7592
FINANZE_USERNAME=your-username
FINANZE_PASSWORD=your-password
```

## Use with Claude Code

From the project folder:

```bash
claude mcp add --scope user --transport stdio finanze -- python -m finanze_mcp
```

Or rely on the bundled `.mcp.json` (project scope): open Claude Code in this directory with
`FINANZE_USERNAME` / `FINANZE_PASSWORD` exported, and it's picked up automatically.

Then just ask Claude things like *"what's my current net worth?"*.

> **Claude Desktop:** add the same `command` / `args` / `env` to your
> `claude_desktop_config.json` instead (Claude Desktop doesn't use `.mcp.json`).

## Optional: live data refresh

Disabled by default. To expose the fetch tools (they make real calls to your banks/brokers and
may require 2FA), set:

```ini
FINANZE_ENABLE_FETCH=true
```

## Development

```bash
pip install -e ".[dev]"
pytest        # tests
ruff check .  # lint
```

## License

[MIT](LICENSE)