Finwise Finance MCP Service
该包将 Finwise Pro 的 /api/finance/* 以及 /api/telegram/* 接口封装为 Model Context Protocol (MCP) 工具，方便 Codex、Claude 等 MCP 客户端直接调用财务/通知能力。
使用步骤
-
安装依赖（在仓库根目录执行）
pnpm install -
本地调试（热重载）
pnpm --filter @vben/finance-mcp-service dev -
生产构建 & 启动
pnpm --filter @vben/finance-mcp-service build FINANCE_BASIC_USERNAME=atai \ FINANCE_BASIC_PASSWORD=wengewudi666808 \ pnpm --filter @vben/finance-mcp-service start
环境变量
| 变量 | 默认值 | 说明 |
|---|---|---|
FINANCE_API_BASE_URL |
http://172.16.74.149:5666 |
后端基地址 |
FINANCE_API_KEY |
(空) | Bearer Token，若未提供则尝试 Basic Auth |
FINANCE_BASIC_USERNAME / FINANCE_BASIC_PASSWORD |
(空) | Basic Auth 凭据 |
FINANCE_API_TIMEOUT |
(空) | 单次请求超时（毫秒） |
FINANCE_MCP_MAX_CONCURRENCY |
4 |
MCP 工具并发执行上限 |
FINANCE_MCP_LOG_LEVEL |
info |
Pino 日志等级 |
Codex/Claude 集成
如需在 Codex 中自动启动该 MCP 服务，可在 config.json 中加入以下配置片段（路径默认位于 ~/.config/codex/config.json）：
{
"mcpServers": {
"finwise-finance": {
"command": "node",
"args": ["apps/finance-mcp-service/dist/index.js"],
"env": {
"FINANCE_BASIC_USERNAME": "atai",
"FINANCE_BASIC_PASSWORD": "wengewudi666808"
},
"cwd": "/Users/fuwuqi/Projects/web-apps/finwise-pro"
}
}
}
配置完成后，重启 Codex 即可在 MCP 面板中看到 finwise-finance，并通过工具调用各类财务接口。
工具清单
- 资金主体：账户、分类、预算、交易、报销、汇率/货币、媒体下载
- 通知配置：Telegram Bot CRUD、实时测试
具体 JSON Schema、入参与返回结构可在 src/tools/finance.ts 中查看，MCP 服务编排逻辑位于 src/server/mcp-server.ts。
CI/CD 部署
- Workflow：
.gitea/workflows/deploy-mcp.yml，默认在main分支 push 且涉及apps/finance-mcp-service/**、pnpm-lock.yaml或pnpm-workspace.yaml时触发，也可通过workflow_dispatch手动执行。 - 流水线阶段：
build-mcp仅安装/构建本服务；deploy-mcp通过appleboy/ssh-action登录172.16.74.149，拉取最新代码并在容器化 Node 20 环境中重新构建。 - 落地路径：服务器
~/kt-financial-system始终与远端main对齐，同时生成/home/atai/run-finance-mcp.sh，可用于systemd/tmux常驻或手动验证。 - 验证方式：部署结束后执行
ssh atai@172.16.74.149 ./run-finance-mcp.sh -- --health（后续会补充自检参数）或直接在 Codex/Claude 中注册该 MCP 服务并调用任一finance_*工具，确认返回 200/0 结果。