AI导哈

个人财务追踪工具

一款自托管的个人财务应用，支持导入银行交易、分类拆分和分析消费模式，作为Finary有限预算工具的替代品。

  • by CalixtheMattei
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 CalixtheMattei/overspending-fit-calou

使用说明

个人支出跟踪器

一个自托管的个人理财应用程序，用于导入银行交易、分类和分析支出模式。作为Finary有限预算工具的替代品而构建。

为什么存在

  • 拆分交易 --共同购买和报销是头等公民
  • 去重 --导入重叠的CSV导出，无重复项
  • 确定性规则 --根据模式自动对交易进行分类
  • 朋友圈 --将特定活动（度假、搬家等）的支出与常规类别分开标记
  • MCP 服务器 --直接从任何MCP主机（如Claude或Codex）查询和管理您的财务

特性

  • CSV导入 --拖放BoursoBank CSV导出，在重叠的日期范围内进行自动重复数据删除
  • 分类账视图 --浏览、筛选和搜索所有交易
  • 分割分配 --跨多个类别分配单个交易
  • 智能分类 --按收款人、标签或金额模式自动对交易进行分类的规则引擎
  • 收款人管理 --将原始银行标签清理成有意义的收款人名称
  • 朋友圈 --将日期范围标记为事件（假期、搬家、项目）并覆盖支出分析
  • 分析 --按类别、收款人和时间段分列的支出明细
  • 内部账户 --在不污染分析的情况下跟踪您自己账户之间的转账

技术栈

层 技术
前端 React 19、Vite、TypeScript、顺风CSS v4、无标题UI
后端 Python 3.11+、FastAPI、SQLAlchemy 2、Alembic
数据库 PostgreSQL 16
MCP服务器 Python 3.12、FastMCP、httpx——stdio和SSE传输
基础设施 Docker编写

快速开始

Docker（推荐）

git clone https://github.com/CalixtheMattei/overspending-fit-calou.git
cd overspending-fit-calou
docker compose up --build
  • 应用程序： http://localhost:5173
  • API文件： http://localhost:8000/docs

启动顺序是健康驱动的：

  • db 必须成为 healthy
  • migrate 运行一次并带代码退出 0
  • backend 开始并成为 healthy
  • frontend 在后端运行状况通过后开始

通过以下方式检查状态：

docker compose ps

Docker开发循环（热重载）

docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build

将其用于前端和后端的绑定挂载和实时重新加载的日常编码。

私有VPS部署（主机Nginx+Tailscale）

当主机级Nginx拥有端口时使用此选项 80/443 以及本地Docker端口的代理。

# 1) Install Docker + Compose plugin (Ubuntu)
curl -fsSL https://get.docker.com | sh

# 2) Clone project
git clone https://github.com/CalixtheMattei/overspending-fit-calou.git
cd overspending-fit-calou

# 3) Create deployment env file
cp .env.example .env
# Edit .env and set strong POSTGRES_PASSWORD before first deploy
# Optionally set DATABASE_URL; if omitted, backend builds it from POSTGRES_*

# 4) Deploy with VPS override (localhost-only published ports)
docker compose -f docker-compose.yml -f docker-compose.vps.yml up -d --build

日志和状态：

docker compose -f docker-compose.yml -f docker-compose.vps.yml ps
docker compose -f docker-compose.yml -f docker-compose.vps.yml logs -f
docker compose -f docker-compose.yml -f docker-compose.vps.yml logs -f backend frontend db

手动设置

先决条件： Node.js 20+，Python 3.11+，PostgreSQL 16

# 1. Start the database
docker compose up -d db

# 2. Backend
cd backend
python -m venv .venv && source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
cp .env.example .env                               # Edit POSTGRES_* (or optional DATABASE_URL)
alembic upgrade head
uvicorn app.main:app --reload                      # http://localhost:8000

# 3. Frontend (in a new terminal)
cd frontend
npm install
npm run dev                                        # http://localhost:5173

MCP 服务器

MCP服务器将后端公开为 模型上下文协议 工具，这样克劳德就可以直接查询和管理您的财务，而无需将数据复制粘贴到提示中。

6个领域的14个工具：

域 工具
交易记录 list_transactions, get_transaction, get_transaction_summary
分析 get_spending_flow, get_payee_analytics, get_category_analytics
时刻 list_moments, get_moment, create_moment, list_moment_tagged_splits
类别 list_categories, get_category_tree
收款人 list_payees, list_automatic_payee_suggestions
规则 list_rules, get_rule_impacts

克劳德代码/克劳德桌面（stdio）

创建一个 .mcp.json 在repo根目录下（gitignored--根据您的环境调整Python命令）：

{
  "mcpServers": {
    "personal-expense": {
      "command": "python",
      "args": ["mcp-server/server.py"],
      "env": { "API_BASE_URL": "http://localhost:8000" }
    }
  }
}

后端必须在Claude Code启动之前运行，才能激活工具。

Docker（SSE）

这 mcp 服务包含在 docker-compose.yml 并在端口3001上运行：

docker compose up mcp        # alongside the rest of the stack

将任何支持SSE的MCP客户端指向 http://localhost:3001/sse.

安全： MCP服务器没有内置身份验证。在专用网络（Tailscale、localhost、内部Docker网络）上运行它。请勿将端口3001暴露于公共互联网。

配置

复制 .env.example 到 .env 并根据需要调整值：

cp .env.example .env

对于Docker，通过环境变量覆盖数据库凭据：

POSTGRES_PASSWORD=my_secure_password docker compose up --build

不保留默认值 postgres/postgres 仅限本地开发之外的证书。

变量 默认值 描述
DATABASE_URL （未设置） 可选完整DSN；如果已设置，则优先于 POSTGRES_*
POSTGRES_USER postgres 数据库用户名
POSTGRES_PASSWORD postgres 数据库密码
POSTGRES_HOST localhost / db （Docker） 数据库主机
POSTGRES_PORT 5432 数据库端口
POSTGRES_DB personal_expense 数据库名称
CORS_ORIGINS ["http://localhost:5173"] 允许的前端来源（首选JSON列表；也接受CSV/single）
APP_ENV development development 或 production
WAIT_FOR_DB_TIMEOUT 60 等待数据库就绪的最长秒数
WAIT_FOR_DB_INTERVAL 1 数据库准备就绪重试之间的秒数
MCP_HOST_PORT 3001 MCP SSE传输的主机端口（仅限Docker）

项目结构

overspending-fit-calou/
├── frontend/src/
│   ├── pages/          # ImportsPage, LedgerPage, RulesPage, AnalyticsPage, MomentsPage
│   ├── components/     # Untitled UI component library
│   └── services/       # API client layer (one service per domain)
├── backend/app/
│   ├── models/         # SQLAlchemy ORM models
│   ├── routers/        # FastAPI REST endpoints
│   └── services/       # Business logic (CSV parsing, dedup, rules engine)
├── mcp-server/
│   └── tools/          # One module per domain (transactions, analytics, moments, …)
├── docs/               # PRDs and contributor guides
├── docker-compose.yml      # Production-like deployment
└── docker-compose.dev.yml  # Dev overrides (hot reload, exposed ports)

CSV格式

设计用于 布尔索银行 以制表符分隔的CSV导出，采用法国十进制格式：

字段 示例 注释
amount -1 300,00 法语格式（空格+逗号）
dateOp 2024-01-15 操作日期
label CARTE 15/01 ... 原始银行标签
supplierFound Carrefour 种子收款人名称

其他采用类似CSV格式的法国银行可能只需稍加调整即可工作。

路线图

  • [x] M0 --项目框架（Docker、Alembic、路由）
  • [x] M1 --CSV导入，带重复数据删除功能
  • [x] 平方米 --分类账、拆分和收款人
  • [x] 立方米 --自动分类规则引擎
  • [x] M4 --分析仪表板
  • [x] M5 --瞬间叠加

文档

贡献

看 贡献.md 用于开发设置、编码约定和PR指南。

许可证

麻省理工学院

相关 MCP