Lunch Money

LunchMoney MCP サーバー

LunchMoney 向けの Model Context Protocol（MCP）サーバー実装です。LunchMoney の API を通じて、個人の財務管理にプログラムからアクセスできます。Claude Desktop に簡単にインストールできる MCP バンドル（.mcpb）としても利用できます。

ご注意 — 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、現在アルファ版）を対象とするようになりました。このサーバーの 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 バンドル
    • Claude Code CLI
    • Codex CLI
    • MCP の手動設定
  • スタンドアロンサーバー
• リモートデプロイ
• プロンプト例
• 利用可能なツール
• 開発
• API リファレンス
• コントリビュート
• ライセンス

概要

この MCP サーバーを使用すると、AI アシスタントやその他の MCP クライアントが LunchMoney のデータを操作でき、財務分析、取引管理、予算編成などを自動化できます。

機能

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

• ユーザー管理 - ユーザーアカウントの詳細にアクセスします
• カテゴリー - カテゴリーとカテゴリーグループの完全な CRUD 操作
• タグ - 取引タグの完全な CRUD 操作
• 取引 - 高度なフィルタリング、一括更新、一括削除、分割、グループ、ファイル添付に対応した完全な CRUD 操作
• 定期項目 - システムが提案する項目を含む、定期的な支出を追跡・管理します
• 予算 - 期間ごとの予算概要、アカウント全体の予算設定、アップサート、削除
• 手動アカウント - 手動管理アカウント（以前は「資産」と呼ばれていました）の完全な CRUD 操作
• Plaid アカウント - 接続済みの銀行口座の一覧表示、取得、同期の実行
• 暗号資産 - 手動での暗号資産残高の完全な CRUD 操作、同期済み暗号資産アカウントの読み取りと更新、対応暗号資産リストの管理
• 残高履歴 - 手動、Plaid、暗号資産、削除済みアカウントの月次残高履歴の読み取り、アップサート、削除

主な機能

• LunchMoney API v2（アルファ版）との完全な統合
• TypeScript と Zod 検証による型安全な実装
• JSON の代わりに TOON エンコーディングを使用した、トークン効率の高い応答により、AI との会話でのトークン使用量を削減
• 拡張が容易なモジュール式アーキテクチャ
• stdio トランスポートを使用した標準的な MCP サーバー実装

使い方

インストール方法

MCP Bundle (.mcpb) - 推奨

このサーバーをインストールする最も簡単な方法は、Claude Desktop に MCP Bundle として追加することです。

1. リリースページから最新の .mcpb ファイルをダウンロードします
2. Claude Desktop を開き、Extensions に移動します
3. 「Install Extension」をクリックし、ダウンロードした .mcpb ファイルを選択します
4. メッセージが表示されたら LunchMoney API トークンを入力します（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 のみを使用します。このサーバーをリモートで公開する方法は 2 つあります。

おまかせ：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 ファイルのみアップロード可能）はどちらの場合にも適用されますが、これは最後の防護策であり、読み取り制限の代わりにはなりません。

マルチテナントに関する警告。 この構成では、1 つのプロセスと共有 API トークンを使って 1 人のユーザーにサービスを提供します。1 つの Node プロセスから複数のユーザーにサービスを提供しようとすると、シングルテナントの設定シングルトンに制約されます。ユーザーごとにプロセスを分けるか、上記の Cloudflare 方式を使用してください（ユーザーごとに独自の isolate が割り当てられます）。

プロンプトの例

LunchMoney MCP サーバーで使用できるプロンプトの例を紹介します。

アカウントの概要

• 「LunchMoney アカウントの詳細を表示して」
• 「現在のアカウント状況は？」

カテゴリ管理

• 「すべての支出カテゴリを一覧表示して」
• 「月額予算を 100 ドルに設定して、「Subscriptions」という新しいカテゴリを作成して」
• 「「Food & Dining」カテゴリの詳細を表示して」
• 「娯楽関連の支出をまとめるカテゴリグループを作成して」
• 「「Unused Category」を削除し、その取引を「Miscellaneous」に振り替えて」

取引管理

• 「先月のすべての取引を表示して」
• 「過去1週間の100ドルを超える取引をすべて検索して」
• 「ショッピングカテゴリで、Amazonでの45.99ドルの新しい支出を作成して」
• 「取引 #12345 の金額を50ドルに変更して」
• 「保留中の取引をすべて表示して」
• 「これらのコーヒーショップでの取引をまとめて」

予算管理

• 「今月の予算概要を表示して」
• 「今月の食料品の予算を500ドルに設定して」
• 「エンターテインメントカテゴリの予算を削除して」
• 「各カテゴリで、予算に対していくら使った？」

手動での口座管理

• 「手動で登録した口座をすべて表示して」
• 「残高10,000ドルの普通預金口座を新しい手動口座として作成して」
• 「投資口座の残高を25,000ドルに更新して」
• 「古いクレジットカード口座を解約して」

定期的な支出

• 「定期的な支出をすべて表示して」
• 「どんなサブスクリプションを利用している？」
• 「今後3か月の定期的な項目を一覧表示して」

銀行連携

• 「連携済みのPlaid口座をすべて表示して」
• 「銀行口座のデータを更新して」
• 「当座預金口座の同期を開始して」

暗号資産

• 「暗号資産の保有状況をすべて表示して」
• 「Bitcoinの残高を0.5 BTCに更新して」
• 「手動で追跡している暗号資産をすべて一覧表示して」
• 「Ledger Cold Storageという名前で、0.85 BTCのコールドウォレット保有分を追加して」
• 「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、および分割・グループの親取引の場合は children を含む）
• create_transactions - 1回の呼び出しで1～500件の取引を登録
• update_transaction - 1件の取引を部分更新
• delete_transaction - 1件の取引を削除（分割・グループ化された取引は不可）
• update_transactions_bulk - 1～500件の取引を一括更新
• delete_transactions_bulk - IDを指定して1～500件の取引を一括削除
• create_transaction_group - 既存の取引から取引グループを作成
• delete_transaction_group - 取引グループを解除
• split_transaction - 1件の取引を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 に型を追加します

ライブラリとしての埋め込み

このパッケージにはサブパスのエントリーポイントが用意されているため、バンドルされた stdio バイナリとしてだけでなく、カスタムトランスポート（たとえば、MCP プロトコルを HTTP 経由で提供する Cloudflare Worker）にも組み込めます。

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." がスローされます。

シングルテナントを前提としています。 設定はモジュールレベルのシングルトンに保持されます。ユーザーごとに独自の isolate が割り当てられる per-isolate ランタイムでは、共有される可変状態をめぐる競合が発生しないため、安全です。一方、共有プロセスのマルチテナント Node ホスト（例：複数のユーザーにサービスを提供する 1 つの Express または Hono プロセス）では安全ではありません。initializeConfig の同時呼び出しが競合し、リクエスト間でトークンが漏えいする可能性があります。そのような用途では、ユーザーごとにフォークするか、パッケージを公開する前にシングルトンをリファクタリングする必要があります。

API リファレンス

このサーバーは LunchMoney API v2 の全機能を実装しています。API の詳細については、次を参照してください。

• LunchMoney v2 API ドキュメント
• v2 移行ガイド
• Model Context Protocol 仕様

コントリビューション

コントリビューションを歓迎します！お気軽にプルリクエストを送信してください。

ライセンス

MIT ライセンス