Fintable MCP

fintable-mcp

一个非官方的 fintable.io MCP（模型上下文协议）服务，让 Claude 等 AI 助手能够直接管理你的财务分类、规则和交易记录——再也不用在多个步骤的向导中反复点击。

注意：这是一个社区项目，并非 fintable.io 官方支持。它通过你的浏览器会话与 Fintable 的 Laravel Livewire 3 后端通信。如果你是 Fintable 的开发者，并希望合作开发官方 MCP 服务或公共 API，请提交 issue——我们很乐意与你合作！🤝

---

功能

安装后，你可以向 Claude 或你喜欢的 MCP 客户端提出这样的请求：

• “创建以下支出分类：办公用品、运输、包装、设备租赁、软件订阅”
• “创建规则：‘Staples’ → 办公用品，‘UPS’ → 运输，‘USPS’ → 运输”
• “运行所有规则，对我的交易进行分类”
• “我在 Ally Bank 的当前账户余额是多少？”
• “列出我所有的分类规则”

再也不用为了设置 20 个分类而反复完成 20 次、每次都有 3 页的向导。只需告诉 Claude 你需要什么。

---

提供的工具

读取操作

工具	描述
fintable_list_accounts	列出所有已连接的银行账户及其余额
fintable_list_categories	列出所有交易分类
fintable_list_rules	列出分类规则（支持分页）
fintable_list_transactions	列出／搜索交易记录，可选筛选条件

写入操作

工具	描述
fintable_create_category	创建单个分类
fintable_create_bulk_categories	一次最多创建 50 个分类
fintable_create_rule	创建分类规则
fintable_create_bulk_rules	一次创建多个规则
fintable_run_all_rules	对未分类的交易执行所有规则
fintable_delete_rule	删除分类规则
fintable_sync_accounts	通过 Plaid 触发银行账户同步
fintable_resync_spreadsheets	将更新推送到 Airtable／Google Sheets

---

安装

前提条件

• Python 3.10+
• 拥有已连接银行账户的 fintable.io 账户
• Claude Desktop（或任何兼容 MCP 的客户端，例如 Cherry Studio）

1. 克隆此仓库

git clone https://github.com/jasoncbraatz/fintable-mcp.git
cd fintable-mcp

2. 安装依赖

pip install -r requirements.txt

或使用 uv（速度更快）：

uv pip install -r requirements.txt

3. 设置身份验证

你有两种选择：自动（推荐）或手动。

选项 A：自动提取 Cookie（推荐）

安装 rookiepy，它会使用你的操作系统凭据，直接从 Chrome 的本地数据库读取 Cookie：

pip install rookiepy

就这么简单。只要你在 Chrome 中登录了 fintable.io，服务每次运行时都会获取最新的 Cookie。无需手动复制，也不用担心过期问题。

选项 A½：自动刷新的 Cookie jar（高级）

如果你希望服务维护自己的会话，而在首次运行后无需 Chrome 或 rookiepy，请在配置中添加 --persist-cookies 标志（参见第 4 步）。这会将会话 Cookie 保存到 ~/.fintable-mcp-cookies.json，并根据服务响应自动更新；只要会话在两次运行之间没有在服务器端过期，就会一直保持有效。

初始种子来自可用的身份验证方式（rookiepy、环境变量等）。之后，服务即可独立运行。

安全提示：此操作会将会话 Cookie 存储在磁盘上。该文件是你主目录中的点文件，不会被公开展示，但任何有权限读取你主目录的人都可能找到它。如果你对此有所顾虑，请使用选项 A。

Python 3.13+ 注意事项：安装 rookiepy 前，你可能需要设置 PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1：

PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1 pip install rookiepy

选项 B：手动导出 Cookie

如果你不想安装 rookiepy（或者你使用的不是 Chrome 浏览器）：

1. 打开 Chrome 并访问 fintable.io，确保已登录
2. 打开开发者工具（F12 或 Cmd+Option+I）
3. 转到 Network 标签页
4. 点击任意一条发往 fintable.io 的请求
5. 在 Request Headers 中找到 Cookie 标头
6. 复制完整的 Cookie 字符串

下一步会将其作为环境变量传入。

4. 配置 Claude Desktop

将以下内容添加到 Claude Desktop 配置文件：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.json

如果使用 rookiepy（选项 A）——无需设置环境变量：

{
  "mcpServers": {
    "fintable": {
      "command": "python",
      "args": ["/absolute/path/to/fintable-mcp/fintable_mcp.py"]
    }
  }
}

如果使用 --persist-cookies（选项 A½）——与 rookiepy 或环境变量搭配，为 Cookie jar 提供初始种子：

{
  "mcpServers": {
    "fintable": {
      "command": "python",
      "args": ["/absolute/path/to/fintable-mcp/fintable_mcp.py", "--persist-cookies"]
    }
  }
}

如果使用手动 Cookie（选项 B）：

{
  "mcpServers": {
    "fintable": {
      "command": "python",
      "args": ["/absolute/path/to/fintable-mcp/fintable_mcp.py"],
      "env": {
        "FINTABLE_COOKIES": "your_full_cookie_string_here"
      }
    }
  }
}

💡 将 /absolute/path/to/fintable-mcp/fintable_mcp.py 替换为你克隆此仓库的实际路径。

5. 重启 Claude Desktop

保存配置后，完全退出并重新启动 Claude Desktop。fintable 工具将显示在 Claude 的工具列表中。

---

身份验证

此服务使用你的 fintable.io 浏览器会话 Cookie 进行身份验证，即你登录后浏览器使用的同一组 Cookie。

Cookie 解析顺序：

0. 持久化 Cookie jar——如果启用了 --persist-cookies，且 ~/.fintable-mcp-cookies.json 中存在最新 Cookie，则使用这些 Cookie。该文件会根据服务的 Set-Cookie 标头自行更新。
1. rookiepy——如果已安装，每次服务启动时都会从 Chrome 本地数据库中提取最新 Cookie。无需维护。
2. FINTABLE_COOKIES 环境变量——来自 Chrome 开发者工具的完整 Cookie 字符串（如果未安装 rookiepy，则作为备用）。
3. FINTABLE_SESSION_COOKIE 环境变量——仅包含会话 Cookie 值（最简单的手动选项）。

启用 --persist-cookies 后，提供初始 Cookie 的方式也会为 Cookie jar 提供初始种子。后续运行时会优先使用 Cookie jar，并且每次服务响应都会自动刷新其中的 Cookie。

此服务绝不会将你的凭据存储到磁盘——服务运行期间，凭据只保存在内存中。

会话过期

如果你使用 rookiepy（推荐），会话过期会自动处理——每次服务器启动时都会从 Chrome 获取新的 Cookie。只需确保你在 Chrome 中保持登录 fintable.io。

如果你使用手动导出 Cookie，Cookie 最终会过期。过期后，服务器会返回身份验证错误。请从 Chrome 重新导出 Cookie，并更新 FINTABLE_COOKIES 环境变量。

---

工作原理（供好奇者和开发者参考）

Fintable.io 是一个使用 Livewire 3 + Alpine.js 构建前端的 Laravel 应用——它没有公开的 REST API。此 MCP 服务会：

1. 进行身份验证：使用浏览器会话 Cookie（CSRF 令牌 + 会话 Cookie）
2. 获取页面：从 wire:snapshot HTML 属性中提取 Livewire 组件快照
3. 调用 Livewire 协议：向 /livewire-{hash}/update 端点发送 POST 请求，其中包含组件快照、方法调用和属性更新
4. 解析 HTML 响应：提取结构化数据（账户、类别、规则、交易）

Livewire 更新路径包含一个哈希值（例如 /livewire-5c7ce5a8/update），应用重新部署时该值可能会改变。服务器会在每次加载页面时，从 data-update-uri HTML 属性中自动发现此路径，因此可以适应不同部署。

---

已知问题和限制

Livewire 哈希值变更

Livewire 更新端点包含一个构建哈希值（例如 /livewire-5c7ce5a8/update），每次部署时都会改变。服务器会在每次获取页面时自动发现该值，但如果 Fintable 大幅调整 Livewire 组件结构或更改组件名称，功能可能会出问题。在没有官方 API 的情况下，这是不可避免的。

HTML 解析易受影响

由于没有 JSON API，读取操作依赖于解析 HTML 结构。如果 Fintable 重新设计界面布局，可能需要更新解析逻辑。这是当前方案最大的维护负担。

未来方向：JSON 端点

理想的解决方案是由 Fintable 提供轻量级 JSON API 端点。这样可以：

• 消除脆弱的 HTML 解析
• 摆脱对 Livewire 哈希值的依赖
• 实现更可靠的集成
• 为其他社区工具和集成创造机会
• 成为产品的一大卖点（支持 MCP 的金融工具是一项差异化优势！）

如果你是正在阅读本文的 Fintable 开发者——哪怕只提供几个经过身份验证的 JSON 端点，用于类别、规则和交易，也能让此服务变得非常可靠，并大幅降低维护难度。欢迎合作设计。🚀

---

安全模型

此服务作为 MCP 客户端的 stdio 子进程，在你的机器上本地运行。它：

• 从不开放网络端口
• 从不将凭据保存到磁盘
• 仅使用你现有的浏览器会话与 fintable.io 通信
• 以单用户、单客户端进程的形式运行

默认情况下，会话 Cookie 仅在服务器运行期间保存在内存中。使用 rookiepy 时，每次启动都会从 Chrome 中重新提取 Cookie——无需环境变量或配置文件。

如果启用了 --persist-cookies，Cookie 会保存到 ~/.fintable-mcp-cookies.json（位于主目录中的点文件）。这是一个可选的权衡：以 Cookie 保存到磁盘为代价，换取会话自动刷新的便利。你可以随时删除此文件以撤销会话。

---

贡献

欢迎提交 PR！未来改进的一些想法：

• 支持按交易日期范围筛选
• 类别组管理（创建／重命名组）
• 重新排列规则优先级
• 将类别／规则导出为 JSON 以进行备份
• 支持多个 Fintable 账户

关于删除的说明： 刻意不支持删除类别——这是一项破坏性操作，最好通过 Fintable 网页界面完成，这样你可以看到全部影响。删除前多一点操作步骤是特性，而不是缺陷。

---

免责声明

本项目与 fintable.io 无关联，未获得其认可，也未获得其官方支持。本项目通过逆向工程分析 Livewire 3 前端协议构建。使用风险自负——底层 Livewire 协议可能会在不另行通知的情况下发生变化。

许可证

MIT - Jason C Braatz