Lunch Money

LunchMoney MCP 服务

这是一个面向 LunchMoney 的 Model Context Protocol（MCP）服务实现，可通过 LunchMoney 的 API 以编程方式访问个人财务管理功能。也提供 MCP Bundle（.mcpb），便于在 Claude Desktop 中安装。

注意 — v3.0.0 移除了 get_all_crypto。 加密货币工具现在使用 LunchMoney 的 v2 加密货币端点，这些端点将手动持有和同步持有拆分为单独的资源，且没有与 v1 的 GET /crypto 等效的合并端点。请将 get_all_crypto 替换为 get_all_manual_crypto 和 get_all_synced_crypto，两者合起来可返回原工具的全部内容，且更多。update_manual_crypto 也移除了 currency 参数。加密货币领域之外没有任何变更；如果你不使用加密货币工具，从 2.x 升级无需采取任何操作。请参阅 CHANGELOG.md。如果你依赖 get_all_crypto，请固定使用 @akutishevsky/lunchmoney-mcp@^2.2.0。

注意 — v2.0.0 是一个破坏性更新。 此服务现在面向 LunchMoney 的 v2 API（https://api.lunchmoney.dev/v2，目前处于 alpha 阶段）。它与此服务的 v1.x 版本不向后兼容：工具名称、字段和端点结构均已更改（例如，assets 现在是 manual_accounts，tags 数组现在是 tag_ids，交易的 asset_id 现在是 manual_account_id，debit_as_negative 开关已移除，预算摘要移至新的 /summary 端点）。完整列表请参阅 CHANGELOG.md。如果你依赖 v1.x，请固定使用 @akutishevsky/lunchmoney-mcp@^1.4.3。

目录

• 概览
• 功能
• 使用方法
  • 安装选项
    • MCP Bundle
    • Claude Code CLI
    • Codex CLI
    • 手动配置 MCP
  • 独立服务
• 远程部署
• 提示词示例
• 可用工具
• 开发
• API 参考
• 贡献
• 许可证

概览

此 MCP 服务可让 AI 助手和其他 MCP 客户端与 LunchMoney 数据交互，从而实现自动化财务洞察、交易管理、预算编制等功能。

功能

全面的工具覆盖

• 用户管理 - 查看用户账户详情
• 分类 - 对分类和分类组进行完整的 CRUD 操作
• 标签 - 对交易标签进行完整的 CRUD 操作
• 交易 - 完整的 CRUD 操作，支持高级筛选、批量更新、批量删除、拆分、分组和文件附件
• 定期项目 - 跟踪和管理定期支出，包括系统建议的项目
• 预算 - 按周期查看预算摘要、设置账户级预算、执行新增或更新，以及删除预算
• 手动账户 - 对手动管理的账户（以前称为“资产”）进行完整的 CRUD 操作
• Plaid 账户 - 列出、获取已连接银行账户的信息，并触发同步
• 加密货币 - 对手动维护的加密货币余额进行完整的 CRUD 操作，读取并刷新已同步的加密货币账户，以及管理支持的加密货币列表
• 余额历史 - 读取、新增或更新及删除手动账户、Plaid 账户、加密货币账户和已删除账户的月度余额历史

主要功能

• 与 LunchMoney API v2（alpha）全面集成
• 使用 TypeScript 和 Zod 验证实现类型安全
• 使用 TOON 编码而非 JSON，提供节省 Token 的响应，减少 AI 对话中的 Token 用量
• 模块化架构，便于扩展
• 使用 stdio 传输的标准 MCP 服务实现

使用方法

安装选项

MCP Bundle（.mcpb）- 推荐

最简单的安装方式是在 Claude Desktop 中安装 MCP Bundle：

1. 从 发布页面 下载最新的 .mcpb 文件
2. 打开 Claude Desktop 并进入 Extensions
3. 点击“Install Extension”，然后选择下载的 .mcpb 文件
4. 根据提示输入 LunchMoney API Token（从 LunchMoney Developer Settings 获取）
5. LunchMoney 工具将立即可用

claude mcp add lunchmoney --transport stdio -e LUNCHMONEY_API_TOKEN=your-api-token-here -- npx -y @akutishevsky/lunchmoney-mcp

claude mcp add lunchmoney --transport stdio -e LUNCHMONEY_API_TOKEN=your-api-token-here -e LUNCHMONEY_DEBUG=true -- npx -y @akutishevsky/lunchmoney-mcp

claude mcp list
claude mcp get lunchmoney

codex mcp add lunchmoney --env LUNCHMONEY_API_TOKEN=your-api-token-here -- npx -y @akutishevsky/lunchmoney-mcp

codex mcp add lunchmoney --env LUNCHMONEY_API_TOKEN=your-api-token-here --env LUNCHMONEY_DEBUG=true -- npx -y @akutishevsky/lunchmoney-mcp

codex mcp list
codex mcp get lunchmoney

{
    "mcpServers": {
        "lunchmoney": {
            "command": "npx",
            "args": ["@akutishevsky/lunchmoney-mcp"],
            "env": {
                "LUNCHMONEY_API_TOKEN": "your-api-token-here",
                "LUNCHMONEY_DEBUG": "true"
            }
        }
    }
}

独立服务

# Run with npx
LUNCHMONEY_API_TOKEN="your-api-token" npx @akutishevsky/lunchmoney-mcp

远程部署

捆绑的 stdio 二进制文件适用于桌面 MCP 客户端，但移动端的 Claude 和 claude.ai 中的自定义连接器功能只支持 HTTP。可通过两种方式远程提供此服务。

即用方案：Cloudflare Workers

lunchmoney-mcp-cloudflare 将此软件包封装为 Cloudflare Worker，并在 MCP 端点前配置 Google 登录和电子邮件允许列表。整个技术栈都能在 Cloudflare 和 Google Cloud 的免费额度内运行，setup.sh 向导会通过一步步的引导完成 KV 创建、OAuth 客户端设置、密钥配置和部署。每位通过身份验证的用户都在自己的 Durable Object 中运行，因此配置单例按用户隔离。

自托管：在自己的主机上使用 HTTP 传输

对于单用户部署，可将 createServer() 接入 StreamableHTTPServerTransport，并通过任意 Node HTTP 框架提供服务。以下是使用 Express 的示例：

import express from "express";
import { createServer } from "@akutishevsky/lunchmoney-mcp/server";
import { initializeConfig } from "@akutishevsky/lunchmoney-mcp/config";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";

initializeConfig(process.env.LUNCHMONEY_API_TOKEN!);
const server = createServer("1.0.0");

const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: () => crypto.randomUUID(),
});
await server.connect(transport);

const app = express();
app.use(express.json());
app.all("/mcp", (req, res) => transport.handleRequest(req, res, req.body));
app.listen(3000);

如果愿意，也可以将 Express 换成 Hono（通过 @hono/node-server）或 Fastify——传输层只需要 Node 的 IncomingMessage 和 ServerResponse。请在 /mcp 前添加自己的身份验证——此软件包不提供传输层身份验证。

在任何远程部署中设置 LUNCHMONEY_ATTACHMENTS_DIR。 attach_file_to_transaction 会从主机文件系统读取调用方提供的路径。在桌面 stdio 服务上，调用方和文件所有者是同一人，这很正常。一旦服务可通过 HTTP 访问，两者就成了不同的主体；不受限制的读取可能会让远程调用方——或遭到提示词注入的模型——从主机获取文件。请将变量指向专用目录，并确保其中不存放其他内容。无论采用哪种方式，内容类型检查（只上传真实的 JPEG/PNG/HEIC/HEIF/PDF 文件）都会生效，但这只是兜底措施，不能替代上述限制。

多租户警告。 此模式通过一个进程和一个共享 API 令牌为一位用户提供服务。如果要通过单个 Node 进程为多位用户提供服务，就会遇到单租户配置单例的限制；请为每位用户单独派生进程，或使用上面的 Cloudflare 方案（每位用户都会获得独立的 isolate）。

示例提示词

以下是一些可与 LunchMoney MCP 服务搭配使用的示例提示词：

账户概览

• “显示我的 LunchMoney 账户详情”
• “我当前的账户状态是什么？”

类别管理

• “列出我的所有支出类别”
• “创建一个名为‘订阅’的新类别，月度预算为 $100”
• “显示‘餐饮’类别的详情”
• “为我的所有娱乐支出创建一个类别组”
• “删除‘未使用的类别’，并将其交易重新分配到‘杂项’”

交易管理

• “显示我上个月的所有交易”
• “查找过去一周金额超过 $100 的所有交易”
• “在 Amazon 的购物类别中创建一笔金额为 $45.99 的新支出”
• “更新交易 #12345，将金额改为 $50”
• “显示我所有待处理的交易”
• “将这些咖啡店交易归为一组”

预算

• “显示我本月的预算摘要”
• “为本月的杂货类别设置 $500 的预算”
• “移除娱乐类别的预算”
• “每个类别中，我已支出多少，与预算相比是多少？”

手动跟踪账户

• “列出我的所有手动账户”
• “为我的储蓄账户创建一个新手动账户，余额为 $10,000”
• “将我的投资账户余额更新为 $25,000”
• “关闭我的旧信用卡账户”

定期支出

• “显示我所有的定期支出”
• “我有哪些订阅？”
• “列出未来 3 个月的定期项目”

银行集成

• “显示我所有已连接的 Plaid 账户”
• “刷新我的银行账户数据”
• “为我的支票账户触发同步”

加密货币

• “显示我所有的加密货币持仓”
• “将我的 Bitcoin 余额更新为 0.5 BTC”
• “列出我手动跟踪的所有加密资产”
• “添加一个冷钱包持仓，数量为 0.85 BTC，名称为 Ledger Cold Storage”
• “刷新我的 Coinbase 账户并显示更新后的余额”
• “我可以手动跟踪哪些加密货币？”

净资产与余额历史记录

• “显示我的净资产在过去 12 个月的变化”
• “我的储蓄账户在 2026 年 3 月的余额是多少？”
• “将我的汽车在 2026 年 6 月的价值设为 $18,000”
• “清除我旧经纪账户的余额历史记录”

分析与洞察

• “本月我的主要支出类别有哪些？”
• “显示所有标记为 ‘vacation’ 的交易”
• “查找所有咖啡店交易”
• “列出所有需要分类的交易”

可用工具

用户工具

• get_user - 获取当前用户详细信息

类别工具

• get_all_categories - 列出所有类别（支持 format 和 is_group 筛选条件）
• get_single_category - 获取特定类别或类别组的详细信息
• create_category - 创建类别或类别组（设置 is_group=true 并提供 children）
• update_category - 更新属性；会替换类别组中的子项列表
• delete_category - 删除类别；传入 force=true 可跳过依赖项检查

标签工具

• get_all_tags - 列出所有标签
• get_single_tag - 根据 ID 获取标签
• create_tag - 创建新标签
• update_tag - 更新标签属性
• delete_tag - 删除标签（使用 force 可跳过依赖项检查）

交易工具

• get_transactions - 列出交易，支持丰富的筛选选项（日期范围、账户、类别、标签、状态、待处理状态、元数据、文件等）
• get_single_transaction - 获取完整的交易详细信息（始终包含 plaid_metadata、custom_metadata、files，以及拆分/分组父项的子项）
• create_transactions - 一次调用插入 1–500 笔交易
• update_transaction - 部分更新一笔交易
• delete_transaction - 删除一笔交易（不能是拆分/分组交易）
• update_transactions_bulk - 批量更新 1–500 笔交易
• delete_transactions_bulk - 按 ID 批量删除 1–500 笔交易
• create_transaction_group - 根据现有交易创建交易组
• delete_transaction_group - 取消交易组
• split_transaction - 将一笔交易拆分为 2–500 笔子交易
• unsplit_transaction - 撤销之前的拆分
• attach_file_to_transaction - 上传本地文件（jpeg/png/heic/heif/pdf，≤10MB），并根据文件内容验证类型
• get_transaction_attachment_url - 获取文件附件的签名下载 URL
• delete_transaction_attachment - 删除文件附件

定期项目工具

• get_recurring_items - 列出指定日期范围内的定期项目（include_suggested 用于系统建议）
• get_single_recurring_item - 根据 ID 获取定期项目

预算工具

• get_budget_summary - 按类别汇总预算（由 /summary 提供支持）；支持切换发生次数、总额和结转资金池
• get_budget_settings - 账户级预算周期和显示设置
• upsert_budget - 为某个类别和周期创建或更新预算
• remove_budget - 移除某个类别和周期的预算

手动账户工具

• get_all_manual_accounts - 列出所有手动管理的账户（以前称为“资产”）
• get_single_manual_account - 根据 ID 获取手动账户
• create_manual_account - 创建新的手动管理账户
• update_manual_account - 更新手动账户的属性
• delete_manual_account - 删除手动账户；还可选择删除其交易记录 / 余额历史记录

Plaid 账户工具

• get_all_plaid_accounts - 列出所有已连接的 Plaid 账户
• get_single_plaid_account - 根据 ID 获取 Plaid 账户
• trigger_plaid_fetch - 触发从 Plaid 获取最新数据（可按日期范围或账户筛选）

加密货币工具

• get_supported_cryptocurrencies - 列出支持手动跟踪的加密货币
• add_supported_cryptocurrency - 根据 CoinGecko 币种页面 URL，将加密货币添加到支持列表
• get_all_manual_crypto - 列出所有手动管理的加密货币余额
• get_single_manual_crypto - 根据 ID 获取单个手动管理的加密货币余额
• create_manual_crypto - 创建手动管理的加密货币资产
• update_manual_crypto - 更新手动加密货币余额的名称、显示名称、机构名称或余额
• delete_manual_crypto - 删除手动加密货币资产（不可撤销）
• get_all_synced_crypto - 列出已同步的加密货币账户及其嵌套的各币种余额
• get_single_synced_crypto - 根据 ID 获取单个已同步的加密货币账户
• get_synced_crypto_balance - 根据币种代码获取已同步加密货币账户中的一笔余额
• refresh_synced_crypto - 触发已同步加密货币账户的余额刷新

余额历史记录工具

• get_balance_history - 获取所有账户的月度余额历史记录（为净资产视图提供数据）；可选的 start_month/end_month（YYYY-MM）范围筛选
• get_account_balance_history - 获取单个账户的月度余额历史记录（manual、plaid、crypto_manual 或 deleted）
• upsert_account_balance_history - 为单个账户创建或更新月度余额记录（仅限过去的月份；要么全部成功，要么全部失败）
• delete_account_balance_history - 删除单个账户的所有历史余额记录
• get_crypto_synced_balance_history - 根据账户 ID + 币种代码获取已同步加密货币持仓的月度余额历史记录
• upsert_crypto_synced_balance_history - 为已同步加密货币持仓创建或更新月度余额记录
• delete_crypto_synced_balance_history - 删除已同步加密货币持仓的所有历史余额记录
• delete_balance_history_entry - 根据 ID 删除单条历史余额记录
• update_deleted_account_details - 更新已删除账户余额历史记录中显示的详细信息（名称、机构、类型、子类型、掩码）

开发

项目结构

lunchmoney-mcp/
├── src/
│   ├── index.ts           # Server entry point
│   ├── config.ts          # Configuration management
│   ├── types.ts           # TypeScript type definitions
│   └── tools/             # Tool implementations
│       ├── user.ts
│       ├── categories.ts
│       ├── tags.ts
│       ├── transactions.ts
│       ├── recurring-items.ts
│       ├── budgets.ts
│       ├── manual-accounts.ts
│       ├── plaid-accounts.ts
│       ├── crypto.ts
│       └── balance-history.ts
├── build/                 # Compiled JavaScript output
├── package.json
├── tsconfig.json
└── README.md

构建

# Build the MCP server
npm run build

# Build MCPB package for distribution
npm run build:mcpb

添加新工具

1. 在 src/tools/ 中创建新文件
2. 使用 MCP SDK 实现工具处理程序
3. 在 src/index.ts 中注册工具
4. 如有需要，在 src/types.ts 中添加类型

作为库嵌入

该软件包提供了子路径入口，可嵌入自定义传输中（例如，通过 HTTP 提供 MCP 协议服务的 Cloudflare Worker），而不仅限于捆绑的 stdio 二进制文件：

import { createServer } from "@akutishevsky/lunchmoney-mcp/server";
import { initializeConfig } from "@akutishevsky/lunchmoney-mcp/config";

initializeConfig(process.env.LUNCHMONEY_API_TOKEN!);
const server = createServer("1.0.0");
// connect `server` to whatever transport you need

调用任何工具之前，必须先调用 initializeConfig，否则第一个请求会抛出 "Configuration not initialized."。

单租户假设。 配置存放在模块级单例中。在按隔离区运行时中这样做是安全的——每位用户都有自己的隔离区，因此不存在会引发竞争的共享可变状态。对于共享进程的多租户 Node 主机（例如，一个 Express 或 Hono 进程为多个用户提供服务）则不安全：并发调用 initializeConfig 会发生竞争，并导致请求间令牌泄漏。这类使用方需要为每位用户单独派生进程，或在公开该软件包之前重构单例。

API 参考

该服务实现了完整的 LunchMoney API v2。如需详细的 API 文档，请参阅：

• LunchMoney v2 API 文档
• v2 迁移指南
• Model Context Protocol 规范

贡献

欢迎贡献！欢迎提交 Pull Request。

许可证

MIT 许可证