ynab-mcpb

演示

_{粘贴收据 → 几秒钟内生成逐项拆分的交易}

可以做什么

工作原理

graph LR
    U(You) -->|Plain English| C[Claude Desktop<br/>or any MCP client]
    C -->|MCP protocol| S[YNAB MCP Server<br/>35 tools]
    S -->|YNAB API| Y[(Your Budget)]

    style S fill:#2563EB,color:#fff,stroke:#1d4ed8
    style Y fill:#16a34a,color:#fff,stroke:#15803d
    style C fill:#7c3aed,color:#fff,stroke:#6d28d9

功能

• 收据明细 — 粘贴收据，即可生成逐项拆分的交易，并自动将税费分摊到各个条目。
• 银行对账（测试版） — 导入银行 CSV，与 YNAB 数据进行模糊匹配，检测缺失或不匹配的交易，并批量应用修正。
• 35 个 YNAB 工具 — 全面覆盖，并支持定期交易和确定性的周期分析。
• 默认确保写入安全 — 预览模式要求使用与确切验证请求绑定的短时有效、单次确认。
• 更精简的工具配置 — 启动时可选择 core、read-only 或 full，无需动态注册。
• 增量同步 — 仅获取自上次请求以来发生变化的数据，保持快速响应。
• Markdown 或 JSON — 所有读取工具都支持 response_format：便于阅读的 Markdown 表格（默认）或结构化 JSON。
• 原生支持 MCP — 支持结构化输出、注释、补全 API 和资源模板。

对账工作原理

sequenceDiagram
    participant You
    participant Claude
    participant MCP as YNAB MCP Server
    participant YNAB

    You->>Claude: "Reconcile my checking<br/>with this CSV"
    Claude->>MCP: reconcile_account(csv_data)
    MCP->>YNAB: Fetch transactions
    YNAB-->>MCP: YNAB transactions
    MCP->>MCP: Parse CSV<br/>Fuzzy-match payees & dates<br/>Detect missing / mismatched
    MCP-->>Claude: Matches + recommendations
    Claude->>You: "Found 47 matches, 3 missing.<br/>Apply changes?"
    You->>Claude: "Yes"
    Claude->>MCP: Apply recommended changes
    MCP->>YNAB: Create / update transactions
    MCP-->>Claude: Done
    Claude->>You: "3 transactions created,<br/>account reconciled."

设置（2 分钟）

1 — 获取 YNAB 令牌

1. 打开 YNAB Web App
2. 前往 账户设置 → 开发者设置 → 新建令牌
3. 复制令牌（仅显示一次）

2 — 安装

{
  "mcpServers": {
    "ynab": {
      "command": "npx",
      "args": ["-y", "@dizzlkheinz/ynab-mcpb@latest"],
      "env": {
        "YNAB_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}

{
  "mcpServers": {
    "ynab": {
      "command": "npx",
      "args": ["-y", "@dizzlkheinz/ynab-mcpb@latest"],
      "env": {
        "YNAB_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}

[mcp_servers.ynab-mcpb]
command = "npx"
args = ["-y", "@dizzlkheinz/ynab-mcpb@latest"]
env = {"YNAB_ACCESS_TOKEN" = "your-token-here"}
startup_timeout_sec = 120

3 — 试试这些提示词

List my budgets and set the default to my main budget.
Show recent transactions in my checking account.
How much did I spend on groceries in the last 30 days?
Create a transaction: $42.18 at Trader Joe's yesterday.

工具（35）

配置

所有选项请参阅 .env.example。

写入模式与兼容性

preview 是较为保守的默认模式。修改操作调用会先运行现有的 dry_run 路径，并返回确认令牌。该令牌会在两分钟后过期，只能使用一次，且仅授权使用相同的规范工具名称和已验证参数。read-only 不会注册 YNAB 修改工具。enabled 会保留启用前的直接写入行为，供明确选择该模式的用户使用。

交易金额现在优先使用 amount_decimal（例如，-12.34）或明确的原始字段 amount_milliunits（-12340）。类别注资同样优先使用 budgeted_decimal 或 budgeted_milliunits。为保持向后兼容，旧字段 amount 和 budgeted 仍可作为已弃用的毫单位别名使用；其含义绝不会通过猜测确定。

工具配置

配置在服务启动时选择，因此客户端收到的 tools/list 响应保持稳定：

• core 包含常用读取工具、交易安全工作流、对账、收据拆分、计划交易审核和支出分析。
• read-only 提供所有明确标注为只读的工具。
• full 提供完整的 35 个工具集，并受所选写入模式限制。

隐私与信任

• 服务进程在本地运行，并通过 YNAB 的 API 与 YNAB 通信。
• 你的 YNAB 个人访问令牌属于敏感信息。请将其存储在 MCP 客户端的机密配置中，切勿将其粘贴到对话、问题、测试固件或日志中。
• 工具返回并包含在对话中的财务数据可能会由 MCP 客户端所选的 AI 提供商处理。分享敏感详情前，请查看该提供商的数据控制措施。
• 交易导出文件会保留在本地磁盘的 YNAB_EXPORT_PATH（或平台默认位置）。服务不会将导出的文件上传到其他位置。
• 若要禁止向 YNAB 写入，请使用 read-only；若要确认具体请求，请使用 preview；仅当有意选择直接写入以兼容特定场景时，才使用 enabled。
• 本开源独立项目与 YNAB 无关联，也未获其认可。

故障排除

开发者指南

git clone https://github.com/dizzlkheinz/ynab-mcpb.git
cd ynab-mcpb
npm ci --ignore-scripts
npm run build
npm test
npm run test:integration

构建和离线测试不需要 YNAB 凭据。npm test 会运行单元测试和性能测试；test:integration 会运行模拟集成测试。使用 test:all、test:coverage 或 test:watch 分别运行完整测试套件、覆盖率测试或监听模式。可直接传入文件或测试名称筛选条件，例如 npm run test:integration -- transactionTools。

若要在本地启动服务，请将 .env.example 复制为 .env，添加令牌，然后运行 npm start。实时冒烟测试需要显式设置 RUN_LIVE_YNAB_TESTS=true，并通过 npm run test:live 运行；设置 SKIP_E2E_TESTS=true 可禁用这些测试。

构建过程不会打包或安装全局工具。若要创建 Claude Desktop 安装包，请先安装官方 CLI 一次（npm install --global @anthropic-ai/mcpb），然后运行 npm run build 和 npm run package:mcpb。使用 npm pack --dry-run --ignore-scripts 查看 npm 包内容。

架构和贡献者指南：CLAUDE.md

对账架构：docs/technical/reconciliation-system-architecture.md

贡献

欢迎提交错误报告和 CSV 边缘情况复现示例，尤其是银行对账方面的内容： 提交问题

欢迎提交 PR——提交前请运行 npm test 和 npm run lint。

许可证

AGPL-3.0