tuskledger-mcp

Tusk Ledger 的模型上下文协议 (Model Context Protocol) 服务器。 让你的 AI 助手能够以类型化的方式访问你的本地个人财务数据 —— 且无需将任何内容发送到你的机器之外。

这是什么

这是一个小型 Python 包，作为本地 模型上下文协议 (Model Context Protocol) 服务器在你的笔记本电脑上运行。一旦你将其添加到 AI 客户端的配置中（Claude Desktop、Cursor、Cowork、Claude Code，任何支持 MCP 的工具），你的助手就可以调用如下工具：

• list_accounts — 查看所有已连接账户的余额和同步状态

• query_transactions — 按日期、账户、类别等进行筛选

• search_transactions — 在商户和备注中进行模糊文本搜索

• get_spending_summary — 获取指定日期范围内的分类支出总额

• get_top_merchants — 查看你支出最多的商户

• get_recurring_subscriptions — 查看 Netflix、健身房等订阅服务

• get_upcoming_bills — 查看未来 30 天的账单及余额变动

• get_net_worth — 查看当前净资产及 12 个月趋势

• get_holdings — 查看所有投资持仓

• get_investments_summary — 查看投资组合汇总及资产配置

• get_retirement_projection — 查看你所保存方案的蒙特卡洛模拟摘要

• run_sync — 触发 Plaid 同步

• list_stale_accounts — 查看数据过期的账户

该服务器与你本地运行在 http://127.0.0.1:8000 的 Tusk Ledger 后端通信。没有任何数据会跨越互联网。 不存在所谓的“MCP 云”——整个过程就是一个在你机器上运行的 Python 进程，与同一台机器上的另一个 Python 进程进行通信。

为什么存在这个项目

Tusk Ledger 是为“代理辅助”用户构建的——即那些可以要求 Claude / Cursor / Cowork 完成五年前无法独自完成的任务的用户。MCP 服务器是实现这一目标最高效的举措：你的助手可以获得类型化、结构化的财务数据访问权限，而无需去抓取 React UI 或猜测数据库架构。

安装后的实际应用示例：

• “将过去 6 个月在 Whole Foods 的交易分类为‘杂货’而不是‘购物’。” → 助手查询这些交易，你确认后，它会创建一条规则。

• “我上个季度在咖啡上花了多少钱？” → 3 秒钟，无需点击 UI。

• “我的净资产今天早上下降了——是什么原因？” → 助手拉取账户、余额和近期交易并进行诊断。

• “我今年能存满 HSA 吗？” → 读取 HSA 额度 + 年初至今的缴款 + IRS 限额，并返回差额。

先决条件

• 正在运行的 Tusk Ledger 安装（主应用程序）

• Python 3.10+

• 支持 MCP 的客户端（Claude Desktop、Cursor、Cowork、Claude Code 等）

安装

选项 A — uvx（推荐；无需永久安装）

如果你有 uv (pip install uv)：

// In your MCP client's config
{
  "mcpServers": {
    "tuskledger": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/BradMorphsters/tuskledger-mcp", "tuskledger-mcp"]
    }
  }
}

uvx 会处理隔离的 Python 环境；不会污染你的全局 Python。服务器在首次调用时会被获取并缓存。

选项 B — 从 GitHub pip install

pip install git+https://github.com/BradMorphsters/tuskledger-mcp

然后将你的 MCP 客户端指向已安装的 tuskledger-mcp 二进制文件：

{
  "mcpServers": {
    "tuskledger": {
      "command": "tuskledger-mcp"
    }
  }
}

（如果你使用的是虚拟环境，请使用 which tuskledger-mcp 得到的完整路径。）

选项 C — 克隆以进行开发

git clone https://github.com/BradMorphsters/tuskledger-mcp
cd tuskledger-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e .

MCP 客户端配置文件的位置

编辑配置后，请重启客户端。服务器会在客户端启动时引导，并在客户端关闭时停止。

配置

两个环境变量，均为可选：

示例：

{
  "mcpServers": {
    "tuskledger": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/BradMorphsters/tuskledger-mcp", "tuskledger-mcp"],
      "env": {
        "TUSKLEDGER_BASE_URL": "http://127.0.0.1:8000",
        "TUSKLEDGER_TIMEOUT_SECONDS": "30"
      }
    }
  }
}

身份验证

此 v0 版本假设你的 Tusk Ledger 后端在运行时启用了 DEV_BYPASS_AUTH=true（这是主仓库 README 中记录的常见单机模式）。如果你保持了身份验证开启，MCP 服务器的调用将返回 401 错误，你会在助手的响应中看到该错误。

支持身份验证的功能已在路线图中。在此之前，如果你同时需要身份验证和 MCP，请仅在需要使用助手时以 DEV_BYPASS_AUTH=true 运行后端，并在完成后将其改回。

此服务器刻意不做的功能

根据设计，v0 版本主要是只读的。服务器不提供以下功能：

• 删除账户、交易、规则或目标

• 修改数据库架构或运行迁移

• 禁用身份验证或轮换加密密钥

• 触碰 Plaid 访问令牌

• 将数据发送到 127.0.0.1 之外的任何地方

理由是：AI 助手应该能够帮助你理解数据并执行安全操作（同步、查询），但不可逆的更改应在 Web UI 中进行，以便你可以看到即将发生的操作。我们可能会在后续版本中添加结构化的写入工具（例如“创建规则”），并带有明确的确认流程，但我们会保持严格的准入标准。

故障排除

Could not reach Tusk Ledger backend at http://127.0.0.1:8000 — 你的 Tusk Ledger 应用未运行。从主仓库运行：./start.sh。

401 Unauthorized（任何工具） — 身份验证已开启。请参阅上方的“身份验证”部分。目前请使用 DEV_BYPASS_AUTH=true 运行。

404 Not Found — 后端没有我们要访问的端点。这通常意味着你使用的 Tusk Ledger 版本较旧。请更新主应用程序并重启你的 MCP 客户端。

工具未出现在你的助手中 — MCP 服务器启动失败。检查客户端的 MCP 服务器日志（Claude Desktop 有一个“查看 MCP 服务器日志”菜单项）。常见原因：配置中的路径错误、Python 不在 PATH 中、未安装 uvx。

常规健康检查 — 从 Tusk Ledger 主仓库运行：./tuskledger doctor。这是整个安装过程的权威诊断工具。

开发

git clone https://github.com/BradMorphsters/tuskledger-mcp
cd tuskledger-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e .
pip install pytest pytest-asyncio
pytest tests/ -v

测试不会启动 MCP 传输层——它们直接使用模拟客户端对调度层进行测试。MCP 协议本身只是一个包装器。

CI 通过 GitHub Actions 在 Python 3.10/3.11/3.12 上运行相同的测试套件（参阅 .github/workflows/ci.yml）。

项目链接

• 主应用: https://github.com/BradMorphsters/tuskledger

• 项目网站: https://www.tuskledger.com

• 供外部浏览的代理文件: https://www.tuskledger.com/llms.txt

• 问题 / 讨论: https://github.com/BradMorphsters/tuskledger-mcp/issues

• 许可证: MIT