fineye-mcp — 面向 AI 代理的 FinEye 个人财务

非官方且独立。 这是一个仅供个人使用、面向社区的命令，针对 FinEye 应用的 API。它与 FinEye 没有任何关联，也未获 FinEye 认可或支持。它只用你自己的登录凭据访问你自己的数据。不提供任何担保——使用风险自负。内嵌的 Supabase anon key 是应用代码中公开的 app 公钥（随 FinEye 客户端一起发布），并非秘密。

这是一个 MCP 服务器，为 AI 代理提供对 FinEye 个人财务数据的类型化访问——涵盖账户、交易、预算、类别、标签、持仓和支出分析；写入操作由明确的安全门把关，删除操作还要再过两扇门。同一份代码还提供了 CLI 和终端仪表盘。

这些都是真实财务记录，不是沙盒。设计从一开始就遵循这一点：默认模式下不能删除任何数据，只读模式甚至不注册删除工具，而一切破坏性调用在确认之前都只是预览。

快速开始

npm install && npm run build
node dist/index.js login          # Google OAuth, token stored at ~/.config/fineye/session.json
npm link                          # optional: puts `fineye` on your PATH

在 Claude Code 中注册：

claude mcp add fineye -s user -- fineye mcp                          # read + write
claude mcp add fineye -s user -e FINEYE_DELETE=1 -- fineye mcp       # read + write + delete
claude mcp add fineye-ro -s user -e FINEYE_READONLY=1 -- fineye mcp  # read-only

任何其他 MCP 客户端使用相同命令：

{
  "mcpServers": {
    "fineye": {
      "command": "node",
      "args": ["/absolute/path/to/fineye-mcp/dist/index.js", "mcp"],
      "env": {},
    },
  },
}

Related MCP server: Lunch Money MCP Server

工具

共 20 个工具，其中 10 个只读。

任何接受 account、category、tag 或 parent 的工具，都支持传名称或 id。参数名直接叫 id 时，传的永远是原始 id。

模式与安全闸门

环境变量决定服务器究竟能做什么：

FINEYE_DELETE 只在服务器注册时设置一次，并在整个会话期间保持生效——所以它是一种能力，而不是一次确认。这才是为什么每次破坏性调用还必须带 confirm: true；否则工具只返回将要删除内容的预览，不会改动任何数据。fineye_bulk 在未传 apply: true 时只是试运行，要删除时必须同时提供 apply 和 confirm。

在 MCP 层之下，客户端按 HTTP 动词执行白名单（src/client.ts 中的 WRITABLE_TABLES、PATCHABLE_TABLES、DELETABLE_TABLES）；其他任何表或 HTTP 动词都会被拒绝。删除只接受单一 id=eq.<id> 过滤器——不存在批量删除路径——而批量删除会先向 /tmp 写入一份 JSON 备份。账户和工作区设置永远不能被删除。 已排期的分期未来账单默认会被排除在批量删除之外，除非你明确请求包含它们。

错误携带机器可读的 code（auth、forbidden、not_found、gate、invalid、network、api），因此代理无需匹配错误消息文本即可区分“没有这笔交易”和“网络断了”。CLI 将同样的 code 映射为退出状态码（3、4、5、4、2、6、1）。

**并发：**写入会整体替换 JSON 字段，而不会合并它们，所以要避免在手机应用中正好同时编辑同一条记录——最后写入者胜出。

操作手册

服务器 instructions 会在每次连接时发送，因此会保持简短。更深的指导——那些真正会让人算错一个数字的陷阱——只会按需加载：

• monthly-review —— 生成一个准确月度概览所用的调用顺序

• safe-bulk-changes —— 试运行、核对匹配数量、然后真正执行

• test-without-polluting —— create → act → delete 的金丝雀测试，以及哪些操作无法撤销

• find-and-fix-categories —— 规则修复未来，批量操作修复过去

它们既作为 MCP 资源提供（fineye://playbooks/<id>），也通过 fineye_playbook 工具提供，因为不同客户端对资源的支持参差不齐。数据模型语义与 CLI 的 agent skill（src/skill/semantics.ts）共享，因此两者不会漂移出相同的定义。

远程访问（HTTP）

对于无法启动本地进程的客户端——比如一个托管的聊天界面——同一服务器也能以 Streamable HTTP 方式访问：

export FINEYE_MCP_TOKEN=$(openssl rand -hex 24)
fineye mcp --http --port 8790          # binds 127.0.0.1; refuses to start without a token

用户再签 tok 换用 request header 即可，这样秘密不会出现在 URL、浏览器历史或代理日志中：

Authorization: Bearer $FINEYE_MCP_TOKEN

如果客户端没有 header 字段，令牌也可以当作 URL 路径使用（https://<host>/<token>）。凭据错误时返回 404，绝不返回 403——这样探测者无法知道这里确实运行着什么。

监听器刻意只在本机的纯 HTTP 上运行：在前面挂一层 TLS 边缘（Cloudflare Tunnel、Tailscale Funnel、VPS 上的反向代理，或者你已经在用的任何方案），随后让客户端指向 https://<your-host>/mcp。

做之前请想清楚。这可把你真实财务数据的活端点放到了互联网上，只靠一个令牌来保护。任何需要无人值守运行的服务都应优先使用 FINEYE_READONLY=1；别让令牌出现在截图中；也不需要反复通过重写文件和重启服务来轮换令牌。

CLI

适合人类和脚本使用的同一套操作。

fineye whoami
fineye accounts [--archived] [--json]
fineye networth [--history] [--json]
fineye transactions [--from <date> --to <date> --account <acc> --category <cat> --search <q>] [--json]
fineye analytics [--month YYYY-MM] [--all] [--leaf] [--by-tag] [--by-merchant --top <n>] [--json]
fineye budget [--month YYYY-MM] | fineye budget history [--limit <n>]
fineye export [--format csv|json] [--from --to] [--out <file>]

fineye add expense <amount> --account <acc> [--category --desc --date --fee]
fineye add transfer <amount> --from <acc> --to <acc> [--to-amount <n>]
fineye tx edit <id> [--desc --category --date --hold]
fineye bulk recategorize <filters> --set-category <cat> [--apply]
fineye rule add --merchant "<exact description>" --mcc <code> --category <cat>

金额使用账户自身币种（十进大单位，例如 42.50）。add transfer 会在两个方向上写入相同金额，与 App 行为一致；如果接收方实际收到的数字不同，请显式传 --to-amount——CLI 绝不按自己想要的方式擅自换算。

fineye ui 打开一个终端仪表盘：账户和余额、带 30 天走势小图的净资产、所选中账户的交易，以及按类目支出的图表。

用 CLI 直接驱动（而不走 MCP server）的代理，还可以用 fineye skill --install 写一份 agent skill 到 ~/.claude/skills/use-fineye/SKILL.md。

工作原理

FinEye 是一个构建于 Supabase 后端之上的 Capacitor 应用。客户端与 App 使用同一组 PostgREST 表和 RPC，通过 PKCE 的 OAuth 以你自己的 Google 账户身份认证（邮箱一次性验证码作为备用）。行级安全保证你只看到属于自己的行。

分层是刻意的：

src/domain/*      pure logic: valuation, analytics, transaction shapes, bulk selection
src/client.ts     the only thing that talks HTTP — and where the allow-lists live
src/mcp/*         the MCP surface: tools, resources, instructions, transports
src/commands/*    the CLI surface over the same domain
src/skill/*       data-model semantics, shared by the MCP instructions and the CLI skill

两个表面（CLI 和 MCP server）都调用相同领域函数处理业务逻辑，因此并不会在一个转账应如何定义、哪些行应视为支出等问题上出现分歧。

领域层还编码了这样几个会出错的数据事实，比如：交易没有“顶层金额”（支出为负，需要用 movements[].sum 求和）；每个账户各自拥有独立币种，因此原始汇总不能直接比较；一笔带两条明细（two-leg）的变动一定是自有账户之间的转账；而分期计划中未来期的分期期项会带有 scheduled 标记，分析时会从你实际已支出的金额中剔除。

开发

npm run typecheck && npm run lint && npm test && npm run build
npm run format

测试套件会拉起见得的可执行文件，通过 stdio 用真实 MCP 通信，所以 transport 例如连接状态确实是被验证过、而不只是假设。

许可证

MIT —— 见 LICENSE。