Skip to main content
Glama
fineye-mcp

fineye-mcp

by mktpavlenko

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: YNAB MCP Server

工具

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

工具

功能

fineye_workspaces

服务器以哪个账户身份登录,以及当前活动工作区

fineye_accounts

余额;view='goals' 查看储蓄目标,view='holdings' 查看加密资产/股票

fineye_networth

以主要币种计算的净资产、分账户明细、可选的每日历史

fineye_transactions

每一行带有推导出的 type(支出/收入/转账)和 scheduled 标记

fineye_analytics

收入/支出/净额及按类别、子类别、标签或商户的支出构成

fineye_budget

时段预算与实际支出对比;用 action='history' 查看过去时段

fineye_categories · fineye_tags

层级结构,用来把名称转为 id

fineye_notifications

应用内收件箱——FinEye 在这里发布产品变更消息

fineye_export

以 CSV 或 JSON 形式内联导出交易

fineye_playbook

操作指导(见下文)

fineye_add · fineye_tx

创建交易;编辑 / 打标签 / 拆分 / 退款 / 复制 / 设置重复

fineye_category · fineye_tag · fineye_account

创建和编辑;类别可以归档(可逆),而不是删除

fineye_budget_set

设置某一时段的总预算

fineye_rules

自动分类规则——只影响未来的交易

fineye_delete · fineye_bulk

永久删除;批量重新归类 / 打标签 / 删除

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

模式与安全闸门

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

env

作用

(无)

读写。删除工具会注册,但每一次删除都会被拒绝。

FINEYE_DELETE=1

删除成为可能,但仍需每次调用都传 confirm: true。

FINEYE_READONLY=1

写入和破坏性工具完全不会注册;保留 12 个只读工具。

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。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables AI agents to interact with your Lunch Money personal finance data, providing tools for managing transactions, categories, budgets, assets, and accounts.
      15
      ISC
    • A
      license
      B
      quality
      A
      maintenance
      Enables AI assistants to interact with YNAB budgets, performing read-only queries by default and optional write operations like creating transactions and managing categories through natural language.
      45
      950 npm
      53
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to access and manage personal financial data from US institutions and manual entries, including transactions, balances, liabilities, and investments.
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to securely access organized personal finance data such as accounts, spending, budgets, goals, investments, and notes, and act on decisions the user approves through Candor.
      4
      -