Lunchmoney MCP

🚀 LunchMoney MCP Server

このLunchMoney MCPサーバーは、LunchMoneyのAPIを通じて、個人の財務管理にプログラムからアクセスできるようにする、Model Context Protocol (MCP) サーバーの実装です。これにより、AIアシスタントや他のMCPクライアントがLunchMoneyのデータとやり取りでき、自動化された財務分析、取引管理、予算管理などが可能になります。

🚀 クイックスタート

このMCPサーバーを使用することで、AIアシスタントや他のMCPクライアントがLunchMoneyのデータとやり取りでき、自動化された財務分析、取引管理、予算管理などが可能になります。

✨ 主な機能

包括的なツールカバレッジ

• ユーザー管理 - ユーザーアカウントの詳細にアクセス
• カテゴリー - 支出カテゴリーの作成、更新、整理
• タグ - 取引タグの管理
• 取引 - 高度なフィルタリングを備えた取引の完全なCRUD操作
• 定期項目 - 定期的な支出の追跡と管理
• 予算 - カテゴリーごとの予算の作成と監視
• 資産 - 手動で管理される資産の追跡
• Plaidアカウント - 接続された銀行口座の管理
• 暗号通貨 - 暗号通貨の保有量の追跡

主要な機能

• LunchMoney API v1との完全な統合
• TypeScriptとZod検証による型安全な実装
• 拡張が容易なモジュール型アーキテクチャ
• stdioトランスポートを使用した標準的なMCPサーバーの実装

💻 使用例

MCPクライアントでの使用

この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 Developer Settings から取得した実際の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. mcpServers セクションにLunchMoneyサーバーの設定を追加します。
3. ファイルを保存し、MCPクライアントを再起動します。
4. これで、LunchMoneyのツールがクライアントで使用可能になります。

必要条件

• システムにNode.js 16以上がインストールされていること
• システムのPATHに npx が利用可能であること
• 適切な権限を持つ有効なLunchMoney APIトークン

スタンドアロンのMCPサーバーとしての使用

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

基本的な使用法

以下は、LunchMoney MCPサーバーで使用できるいくつかの例示的なプロンプトです。

アカウント概要

• "Show me my LunchMoney account details"
• "What's my current account status?"

カテゴリー管理

• "List all my spending categories"
• "Create a new category called 'Subscriptions' with a monthly budget of $100"
• "Show me details for my 'Food & Dining' category"
• "Create a category group for all my entertainment expenses"
• "Delete the 'Unused Category' and reassign its transactions to 'Miscellaneous'"

取引管理

• "Show me all transactions from last month"
• "Find all transactions over $100 in the past week"
• "Create a new expense for $45.99 at Amazon in the Shopping category"
• "Update transaction #12345 to change the amount to $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"
• "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"
• "Update my investment account balance to $25,000"

定期的な支出

• "Show me all my recurring expenses"
• "What subscriptions do I have?"
• "List recurring items for the next 3 months"

銀行統合

• "Show me all my connected Plaid accounts"
• "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"
• "List all my manually tracked crypto assets"

分析と洞察

• "What are my top spending categories this month?"
• "Show me all transactions tagged as 'vacation'"
• "Find all transactions at coffee shops"
• "List all transactions that need to be categorized"

📚 ドキュメント

利用可能なツール

ユーザーツール

• get_user - 現在のユーザーの詳細を取得

カテゴリーツール

• get_all_categories - すべての支出カテゴリーをリスト表示
• get_single_category - 特定のカテゴリーの詳細を取得
• create_category - 新しいカテゴリーを作成
• create_category_group - カテゴリーグループを作成
• update_category - カテゴリーのプロパティを更新
• add_to_category_group - カテゴリーをグループに追加
• delete_category - カテゴリーを削除
• force_delete_category - データのクリーンアップを伴う強制削除

タグツール

• get_all_tags - すべての利用可能なタグをリスト表示

取引ツール

• get_transactions - 広範なフィルタリングオプションで取引をリスト表示
• get_single_transaction - 取引の詳細情報を取得
• create_transactions - 新しい取引を作成
• update_transaction - 既存の取引を更新
• unsplit_transactions - 分割グループから取引を削除
• get_transaction_group - 取引グループの詳細を取得
• create_transaction_group - 取引グループを作成
• delete_transaction_group - 取引グループを削除

定期項目ツール

• get_recurring_items - 指定された期間の定期項目をリスト表示

予算ツール

• get_budget_summary - 指定された期間の予算概要を取得
• upsert_budget - 予算額を作成または更新
• remove_budget - カテゴリーの予算を削除

資産ツール

• get_all_assets - すべての手動管理される資産をリスト表示
• create_asset - 新しい資産を作成
• update_asset - 資産のプロパティを更新

Plaidアカウントツール

• get_all_plaid_accounts - すべての接続されたPlaidアカウントをリスト表示
• trigger_plaid_fetch - Plaidから最新のデータを取得するトリガー

暗号通貨ツール

• get_all_crypto - すべての暗号通貨資産をリスト表示
• update_manual_crypto - 手動管理される暗号通貨の残高を更新

開発

プロジェクト構造

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 Documentation
• Model Context Protocol Specification

コントリビューション

コントリビューションは大歓迎です！ぜひプルリクエストを送信してください。

📄 ライセンス

MITライセンス