内容
# Fineco 银行 MCP 服务器
一个 [模型上下文协议](https://modelcontextprotocol.io)（MCP）服务器，用于将 **Fineco 银行** 的个人财务导出数据导入本地 SQLite 数据库，并将其作为工具提供，用于现金流和投资组合财富的 LLM 驱动分析。
## 功能特点
- 解析 Fineco 银行导出文件（账户变动、投资组合快照、投资组合订单）
- 将数据存储在本地 SQLite 数据库中，自动去重
- 支持 **增量导入** — 重新运行部分导出数据，只添加新记录
- 暴露 5 种 MCP 工具，可供任何 MCP 兼容的客户端（Claude Desktop 等）使用
## 要求
- Python 3.10+
- [uv](https://docs.astral.sh/uv/)（推荐）或 pip
## 安装
### 1. 克隆仓库
```bash
git clone https://github.com/morettimarco/fineco-mcp.git
cd fineco-mcp
```
### 2. 安装依赖
使用 `uv`（推荐）：
```bash
uv pip install -e .
```
或使用 pip：
```bash
pip install -e .
```
这将安装 `mcp[cli]`、`openpyxl` 和 `xlrd`。
### 3. 配置 Claude Desktop
将服务器添加到您的 Claude Desktop 配置文件中：
- **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"]
}
}
}
```
将 `/absolute/path/to/fineco-mcp/` 替换为实际的仓库克隆路径。
如果您使用了 `uv`，可以使用 `uv run` 形式代替：
```json
{
"mcpServers": {
"fineco": {
"command": "uv",
"args": ["run", "python", "/absolute/path/to/fineco-mcp/server.py"]
}
}
}
```
编辑配置文件后，请重启 Claude Desktop。
## 使用
### 从 Fineco 银行导出文件
从 Fineco 网络平台下载导出文件：
| 导出类型 | 典型文件名 | 在哪里找到 |
|---|---|---|
| 账户变动 | `movements_YYYYMMDD.xlsx` | 账户 → 变动 → 导出 |
| 投资组合快照 | `portafoglio-export.xls` | 投资组合 → 导出 |
| 投资组合订单 | `Lista Titoli.xlsx` | 投资组合 → 订单 → 导出 |
> **注意：**尽管文件扩展名为 `.xls`/`.xlsx`，但这些文件实际上是纯逗号分隔的文本（CSV）。服务器可以自动处理。
将文件放在一个文件夹中，然后询问 Claude：
> *"导入我的 Fineco 导出文件从 ~/Downloads"*
### 可用的 MCP 工具
| 工具 | 描述 |
|---|---|
| `ingest_files(directory_path)` | 扫描文件夹中的 Fineco 导出文件并将新记录加载到数据库 |
| `get_current_liquidity()` | 返回最新的账户余额 |
| `search_account_transactions(start_date, end_date, keyword, category, limit)` | 过滤和搜索账户变动 |
| `get_portfolio_positions()` | 返回当前持仓市值和盈亏 |
| `search_portfolio_orders(isin, operation_type, sign, limit)` | 搜索买卖股息历史 |
### 示例提示
- *"我的当前账户余额是多少？*"
- *"显示我上个月在 'Alimentari' 类别的所有支出"*
- *"2025 年我花了多少钱用于订阅？"*
- *"我的当前投资组合资产配置情况如何？"*
- *"显示我收到的所有 ISIN IE00B4L5Y983 股息"*
### 增量导入
您不需要每次导出完整的历史记录。服务器使用 SHA-256 哈希算法对每个记录的关键字段进行哈希，以检测重复记录。只需导出最近的期间并再次运行 `ingest_files` — 只有真正新的记录会被添加。
## 数据库
SQLite 数据库（`fineco_data.db`）在首次运行时自动在项目文件夹中创建。它包含四个表：
- `account_transactions` — 所有账户变动，含带符号金额
- `portfolio_orders` — 完整的买卖和股息历史
- `portfolio_snapshot` — 当前投资组合持仓（每次导入快照时替换）
- `balances` — 带时间戳的账户余额历史
## 隐私
数据库包含个人财务数据。数据 **仅存储在本地**，并通过 `.gitignore` 排除在版本控制之外。永远不要将 `fineco_data.db` 或您的 Fineco 导出文件提交到公共仓库。
