Lunchmoney MCP

🚀 LunchMoney MCP 服务器

LunchMoney MCP 服务器是一个针对 LunchMoney 的模型上下文协议（MCP）服务器实现，它通过 LunchMoney 的 API 为个人财务管理提供了编程式访问方式。借助该服务器，用户可以利用程序自动化地进行财务洞察分析、交易管理、预算规划等操作。

🚀 快速开始

若要使用此 MCP 服务器与任何兼容 MCP 的客户端（如 Claude Desktop）进行交互，你需要将其添加到客户端的配置中。

配置

服务器可以在你的 MCP 客户端配置文件中进行配置。具体位置和格式可能因客户端而异，但通常遵循以下模式：

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

请将 "your-api-token-here" 替换为你从 LunchMoney 开发者设置 获取的实际 LunchMoney API 令牌。

常见 MCP 客户端配置位置

不同的 MCP 客户端将其配置存储在不同的位置：

• Claude Desktop：
  • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows：%APPDATA%\Claude\claude_desktop_config.json
  • Linux：~/.config/Claude/claude_desktop_config.json
• 其他 MCP 客户端：请查看客户端文档以获取配置文件的位置。

设置步骤

1. 找到你的 MCP 客户端配置文件（如果不存在则创建）。
2. 将 LunchMoney 服务器配置添加到 mcpServers 部分。
3. 保存文件并重启 MCP 客户端。
4. 此时，LunchMoney 工具应已在你的客户端中可用。

要求

• 系统中安装了 Node.js 16 或更高版本。
• 系统路径中可使用 npx。
• 拥有具有适当权限的有效 LunchMoney API 令牌。

作为独立 MCP 服务器运行

# 使用 npx 运行
LUNCHMONEY_API_TOKEN="your-api-token" npx @akutishevsky/lunchmoney-mcp

✨ 主要特性

全面的工具覆盖

• 用户管理 - 访问用户账户详细信息。
• 类别管理 - 创建、更新和组织消费类别。
• 标签管理 - 管理交易标签。
• 交易管理 - 对交易进行完整的 CRUD 操作，并支持高级过滤。
• 定期项目管理 - 跟踪和管理定期费用。
• 预算管理 - 按类别创建和监控预算。
• 资产跟踪 - 跟踪手动管理的资产。
• Plaid 账户管理 - 管理连接的银行账户。
• 加密货币管理 - 跟踪加密货币持有量。

关键能力

• 与 LunchMoney API v1 完全集成。
• 使用 TypeScript 和 Zod 验证实现类型安全。
• 模块化架构，便于扩展。
• 使用标准输入输出传输实现标准 MCP 服务器。

💻 使用示例

基础用法

以下是一些可以与 LunchMoney MCP 服务器一起使用的示例提示：

# 账户概述
- "Show me my LunchMoney account details"（显示我的 LunchMoney 账户详细信息）
- "What's my current account status?"（我当前的账户状态如何？）

# 类别管理
- "List all my spending categories"（列出我所有的消费类别）
- "Create a new category called 'Subscriptions' with a monthly budget of $100"（创建一个名为 'Subscriptions' 的新类别，每月预算为 100 美元）
- "Show me details for my 'Food & Dining' category"（显示我的 'Food & Dining' 类别的详细信息）
- "Create a category group for all my entertainment expenses"（为我所有的娱乐费用创建一个类别组）
- "Delete the 'Unused Category' and reassign its transactions to 'Miscellaneous'"（删除 'Unused Category' 类别，并将其交易重新分配到 'Miscellaneous' 类别）

# 交易管理
- "Show me all transactions from last month"（显示我上个月的所有交易）
- "Find all transactions over $100 in the past week"（查找过去一周内超过 100 美元的所有交易）
- "Create a new expense for $45.99 at Amazon in the Shopping category"（在购物类别中创建一笔在亚马逊的 45.99 美元新费用）
- "Update transaction #12345 to change the amount to $50"（将交易 #12345 的金额更新为 50 美元）
- "Show me all pending transactions"（显示所有待处理的交易）
- "Group these coffee shop transactions together"（将这些咖啡店交易分组）

# 预算管理
- "Show me my budget summary for this month"（显示我本月的预算摘要）
- "Set a budget of $500 for Groceries this month"（为本月的杂货设定 500 美元的预算）
- "Remove the budget for Entertainment category"（移除娱乐类别的预算）
- "How much have I spent vs budgeted in each category?"（我在每个类别中的实际花费与预算相比如何？）

# 资产跟踪
- "List all my assets"（列出我所有的资产）
- "Create a new asset for my savings account with a balance of $10,000"（为我的储蓄账户创建一个余额为 10,000 美元的新资产）
- "Update my investment account balance to $25,000"（将我的投资账户余额更新为 25,000 美元）

# 定期费用管理
- "Show me all my recurring expenses"（显示我所有的定期费用）
- "What subscriptions do I have?"（我有哪些订阅服务？）
- "List recurring items for the next 3 months"（列出未来 3 个月的定期项目）

# 银行集成
- "Show me all my connected Plaid accounts"（显示我所有连接的 Plaid 账户）
- "Refresh my bank account data"（刷新我的银行账户数据）
- "Trigger a sync for my checking account"（触发我的支票账户同步）

# 加密货币管理
- "Show me all my crypto holdings"（显示我所有的加密货币持有量）
- "Update my Bitcoin balance to 0.5 BTC"（将我的比特币余额更新为 0.5 BTC）
- "List all my manually tracked crypto assets"（列出我所有手动跟踪的加密货币资产）

# 分析与洞察
- "What are my top spending categories this month?"（我本月的主要消费类别有哪些？）
- "Show me all transactions tagged as 'vacation'"（显示所有标记为 'vacation' 的交易）
- "Find all transactions at coffee shops"（查找所有在咖啡店的交易）
- "List all transactions that need to be categorized"（列出所有需要分类的交易）

📚 详细文档

可用工具

🔧 技术细节

项目结构

lunchmoney-mcp/
├── src/
│   ├── index.ts           # 服务器入口点
│   ├── config.ts          # 配置管理
│   ├── types.ts           # TypeScript 类型定义
│   └── tools/             # 工具实现
│       ├── user.ts
│       ├── categories.ts
│       ├── tags.ts
│       ├── transactions.ts
│       ├── recurring-items.ts
│       ├── budgets.ts
│       ├── assets.ts
│       ├── plaid-accounts.ts
│       └── crypto.ts
├── build/                 # 编译后的 JavaScript 输出
├── package.json
├── tsconfig.json
└── README.md

构建项目

npm run build

添加新工具

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

📚 API 参考

服务器实现了完整的 LunchMoney API v1。有关详细的 API 文档，请参阅：

• LunchMoney API 文档
• 模型上下文协议规范

🤝 贡献

欢迎贡献代码！请随时提交拉取请求。

📄 许可证

本项目采用 MIT 许可证。