内容
# 我的财务 MCP
一个用于个人财务的远程MCP服务器 - 通过语音记录支出，拍摄收据照片，导入整个银行对账单，并为您计算预算，趋势和净资产，以任何货币。
**网站：** [myfinance-mcp.com](https://myfinance-mcp.com) · 免费测试 · 由 [Rteam](https://rteam.agency) 构建
## 快速开始
已经托管并准备就绪 - 只需将其连接到您的MCP客户端：
```
https://myfinance-mcp.com/mcp
```
**在 Claude.ai 上：** 自定义 → 连接器 → **+** → 添加自定义连接器 → 粘贴网址 → 连接。留空 OAuth 客户端 ID 和客户端密码字段 - 填写它们会破坏登录。
**在 ChatGPT 上：** 设置 → 应用程序 → 创建应用程序 → 粘贴网址 → 选择 OAuth → 创建。
首次连接时，您可以使用 Google 登录或使用电子邮件和密码注册。您的数据在重新连接时保持不变。
## 为什么
- **无需应用，无需表单，无需电子表格。** “在 Lidl 花费 24.50 欧元购买杂货”就是整个工作流程。
- **每个数字都在 SQL 中计算。** 服务器拥有数据和数学运算；AI 读取结果，它永远不会猜测算术。
- **任意货币。** 交易保留其原始货币；兑换率在交易日期冻结，因此历史永远不会被重写。
- **单条消息中的对账单。** 丢弃 CSV/PDF 导出；数百行导入只需一次调用，具备幂等去重，手动记录的双重记录合并，总额核对。
- **个人 vs 商业。** 账户和交易上的实体标签，可在任何地方过滤，包含在 CSV 导出中，供您的会计师使用。
- **聊天中的仪表盘。** 预算，趋势，摘要和账户以交互式面板（MCP 应用程序）形式直接在对话中呈现。
## 技术栈
- **Bun** - 运行时和包管理器
- **Express** - HTTP 层
- **MCP SDK** - 模型上下文协议（Model Context Protocol），基于 Streamable HTTP（无状态）
- **OAuth 2.1** - PKCE + 动态客户端注册，Google 登录可选
- **Prisma + PostgreSQL** - 所有金额作为 `numeric`，所有统计数据作为 SQL 聚合
- **Docker** - 单容器部署
## MCP 工具
| 工具 | 描述 |
| --------------------- | -------------------------------------------------------------------------------------------------- |
| `log_expense` | 记录一次购买，账单或收据（负金额 = 退款） |
| `log_income` | 记录收入：工资，发票，退款，利息 |
| `log_transfer` | 在账户之间转移资金，支持跨货币；从不计为支出 |
| `log_balance` | 在某日期锚定账户余额；后续流动性计算从快照开始 |
| `import_transactions` | 批量对账单导入（最多 500 行/调用）：根据银行参考或派生密钥去重，合并双重记录，核对结算 |
| `create_account` | 创建具有货币和个人/商业实体的银行/卡/现金/投资账户 |
| `get_accounts` | 所有账户的余额和净资产，转换为基准货币 |
| `get_summary` | 按类别，商家或月份的期间总额，由服务器端计算 |
| `get_transactions` | 列出和过滤原始交易 |
| `get_trends` | 月环比支出趋势和差异 |
| `set_budget` | 按类别或整体设定每月上限 |
| `get_budget_progress` | 具有剩余天数的实时预算进度；呈现为仪表盘 |
| `update_transaction` | 修复现有交易的任何字段 |
| `delete_transaction` | 按 ID 删除交易 |
| `delete_transactions` | 按 ID 批量删除 |
| `get_settings` | 基准货币和时区 |
| `update_settings` | 更改基准货币或时区 |
| `export_transactions` | 完整 CSV 导出（包括会计师移交的实体列） |
| `delete_account` | 永久删除用户账户和所有数据（GDPR 删除） |
| `ping` | 健康和身份验证检查 |
## MCP 应用
四个工具返回一个交互式仪表盘（`ui://myfinancemcp/dashboard`），直接在支持 MCP 应用的客户端聊天中渲染：预算环，月度趋势，类别摘要和账户/净资产面板。具备浅色和深色主题感知。
## 安全与隐私
- 收据照片由您的 AI 客户端解析；图像从未到达此服务器。
- 金额，商家和备注从未写入服务器日志（盲日志）；遥测仅存储事件类型和 ID。
- 使用 OAuth 2.1 和 PKCE，加密令牌，限速登录。
- CSV 导出和即时完全删除是工具，不是支持票。
- 已托管实例：欧盟数据驻地，按您的账户密钥进行行级安全。
请参阅 [SECURITY.md](SECURITY.md) 获取披露政策。
## 自主托管
MIT 许可；可在 Bun 和 Postgres 运行的任何地方运行。
### 1. Postgres
任何 PostgreSQL 15+ 都适用。 [Supabase](https://supabase.com) 免费层是一个不错的选择：创建一个项目并复制 **会话池连接字符串**（IPv4）。
应用模式：
```bash
bun install
bunx prisma db push
```
### 2. 环境变量
| 变量 | 描述 |
| ----------------------------- | ------------------------------------------------------------------ |
| `PORT` | 服务器端口（默认 `8788`） |
| `BASE_URL` | 服务器的公共 URL（OAuth 发行者） |
| `DATABASE_URL` | Postgres 连接字符串 |
| `MYFINANCE_MCP_EMAIL` | 引导用户电子邮件 |
| `MYFINANCE_MCP_PASSWORD_HASH` | 引导用户密码哈希（参见下文） |
| `GOOGLE_CLIENT_ID` | _(可选)_ Google OAuth 客户端 ID，用于“继续使用 Google” |
| `GOOGLE_CLIENT_SECRET` | _(可选)_ Google OAuth 客户端密钥 |
| `RESEND_API_KEY` | _(可选)_ Resend 密钥，用于新注册电子邮件通知 |
| `NOTIFY_EMAIL` | _(可选)_ 注册通知发送到的电子邮件 |
| `FROM_EMAIL` | _(可选)_ 验证的通知发送者 |
生成密码哈希：
```bash
bun -e "console.log(await Bun.password.hash(process.argv[1]))" 'your-password'
```
### 3. 运行
```bash
docker compose up -d # 使用附带的 Dockerfile，端口 8788
```
在前面放置 nginx（或任何 TLS 终止代理），并将 `BASE_URL` 指向您的域名。可选的静态登录页面位于 [`site/`](site/) 中 - 如果需要，请从同一来源提供服务。
## 开发
```bash
bun install
cp .env.example .env # 填写您的值
bun run dev # 在 :8788 上热重载
bun run e2e # 自包含端到端套件（启动自己的服务器）
bun run lint
```
端到端套件涵盖了完整的 OAuth 流程（发现，动态注册，PKCE，刷新轮换），每个工具，声明导入重复数据删除语义和 GDPR 删除。
## API 端点
| 端点 | 描述 |
| ---------------------------------------------- | ---------------------------------------- |
| `POST /mcp` | MCP 端点（Bearer 身份验证） |
| `GET /health` | 健康检查 |
| `GET /.well-known/oauth-authorization-server` | OAuth 元数据发现 |
| `GET /.well-known/oauth-protected-resource/mcp`| 受保护资源元数据 |
| `POST /register` | 动态客户端注册 |
| `GET /authorize` | OAuth 授权（登录页面） |
| `POST /token` | 令牌交换 |
| `GET /auth/google` | Google 登录启动（配置时） |
| `GET /api/stats` | 公共聚合计数器（仅限计数，无金额） |
## 许可证
[MIT](LICENSE) - Rteam FZE LLC
