Content
# Fineco Bank MCP Server
A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that ingests personal finance exports from **Fineco Bank** into a local SQLite database and exposes them as tools for LLM-powered analysis of cash flow and portfolio wealth.
## Features
- Parses Fineco Bank export files (account movements, portfolio snapshot, portfolio orders)
- Stores data in a local SQLite database with automatic deduplication
- Supports **incremental ingestion** — re-run with partial exports and only new records are added
- Exposes 5 MCP tools consumable by any MCP-compatible client (Claude Desktop, etc.)
## Requirements
- Python 3.10+
- [uv](https://docs.astral.sh/uv/) (recommended) or pip
## Installation
### 1. Clone the repository
```bash
git clone https://github.com/morettimarco/fineco-mcp.git
cd fineco-mcp
```
### 2. Install dependencies
With `uv` (recommended):
```bash
uv pip install -e .
```
Or with pip:
```bash
pip install -e .
```
This installs `mcp[cli]`, `openpyxl`, and `xlrd`.
### 3. Configure Claude Desktop
Add the server to your Claude Desktop configuration file:
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"fineco": {
"command": "python3",
"args": ["/absolute/path/to/fineco-mcp/server.py"]
}
}
}
```
Replace `/absolute/path/to/fineco-mcp/` with the actual path where you cloned the repo.
If you used `uv`, you can use the `uv run` form instead:
```json
{
"mcpServers": {
"fineco": {
"command": "uv",
"args": ["run", "python", "/absolute/path/to/fineco-mcp/server.py"]
}
}
}
```
Restart Claude Desktop after editing the config.
## Usage
### Exporting files from Fineco Bank
Download your exports from the Fineco web platform:
| Export type | Typical filename | Where to find it |
|---|---|---|
| Account movements | `movements_YYYYMMDD.xlsx` | Conto corrente → Movimenti → Esporta |
| Portfolio snapshot | `portafoglio-export.xls` | Rubrica Titoli → Esporta |
| Portfolio orders | `Lista Titoli.xlsx` | Dossier Titoli → Lista Titoli → Esporta |
> **Note:** Despite the `.xls`/`.xlsx` extensions, these files are plain comma-separated text (CSV). The server handles this automatically.
Place the files in a folder, then ask Claude:
> *"Ingest my Fineco exports from ~/Downloads"*
### Available MCP Tools
| Tool | Description |
|---|---|
| `ingest_files(directory_path)` | Scan a folder for Fineco exports and load new records into the database |
| `get_current_liquidity()` | Return the latest account balance |
| `search_account_transactions(start_date, end_date, keyword, category, limit)` | Filter and search account movements |
| `get_portfolio_positions()` | Return current holdings with market value and P&L |
| `search_portfolio_orders(isin, operation_type, sign, limit)` | Search buy/sell/dividend history |
### Example prompts
- *"What is my current account balance?"*
- *"Show me all expenses in the 'Alimentari' category last month"*
- *"How much have I spent on subscriptions in 2025?"*
- *"What is my current portfolio allocation by asset class?"*
- *"Show me all dividends received for ISIN IE00B4L5Y983"*
### Incremental ingestion
You do not need to export your full history every time. The server uses SHA-256 hashing on each record's key fields to detect duplicates. Simply export the most recent period and run `ingest_files` again — only genuinely new records will be added.
## Database
The SQLite database (`fineco_data.db`) is created automatically in the project folder on first run. It contains four tables:
- `account_transactions` — all account movements with signed amounts
- `portfolio_orders` — full history of buys, sells, and dividends
- `portfolio_snapshot` — current portfolio positions (replaced on each snapshot import)
- `balances` — timestamped account balance history
## Privacy
The database contains personal financial data. It is stored **locally only** and is excluded from version control via `.gitignore`. Never commit `fineco_data.db` or your Fineco export files to a public repository.
