Money Lover MCP サーバー

非公式の Money Lover REST API をラップする、Model Context Protocol (MCP) サーバーの Node.js 実装です。このサーバーは、認証、ウォレット、カテゴリ、取引、イベント、負債、および静的設定をカバーする 27 個の MCP ツールを公開しており、AI アシスタントや MCP 対応クライアントが個人財務データを照会および管理できるようにします。

機能

• EMAIL/PASSWORD 環境変数による自動認証 — ほとんどのツールでトークンの受け渡しは不要です。

• ユーザー情報、ウォレット、カテゴリ、取引、イベント、負債、アイコン、プロバイダー、静的設定をカバーする 23 個の読み取りツール。

• 4 個の書き込みツール: 取引、ウォレット、カテゴリの作成、更新、削除。

• LLM のコンテキストを管理しやすくするために、大きな応答は自動的に切り詰められます（limit パラメータで設定可能）。

• Claude Code、Claude Desktop、Cursor、およびあらゆる MCP ホストと互換性のある Stdio ベースのサーバー。

• ~/.moneylover-mcp/ 配下でのメールごとのトークンキャッシュと、認証エラー時の自動更新。

Related MCP server: YNAB Assistant

前提条件

• Node.js 22 以降。

• Money Lover アカウントの資格情報。

インストール

npm install

使用方法

Stdio 経由で MCP サーバーを起動します:

npm start

プロジェクトスコープの設定 (Claude Code)

プロジェクトのルートに .mcp.json を追加します:

{
  "mcpServers": {
    "mcp-moneylover": {
      "command": "node",
      "args": ["/absolute/path/to/moneylover-mcp/src/server.js"],
      "env": {
        "EMAIL": "your@email.com",
        "PASSWORD": "your-password"
      }
    }
  }
}

そして .claude/settings.json で有効にします:

{ "enabledMcpjsonServers": ["mcp-moneylover"] }

グローバル設定 (Claude Desktop / Cursor)

{
  "mcpServers": {
    "mcp-moneylover": {
      "command": "npx",
      "args": ["@ferdhika31/moneylover-mcp@latest"],
      "env": {
        "EMAIL": "your@email.com",
        "PASSWORD": "your-password"
      }
    }
  }
}

利用可能なツール

認証

ユーザー

ウォレット

カテゴリ

取引

静的設定 & 設定

ツールの使用例

プロンプトの例、必須フィールドとオプションフィールド、注意点、およびすべてのツールに共通するマルチステップパターンの詳細: docs/examples.md

ライブラリの使用

import { MoneyloverClient } from './src/moneyloverClient.js';

const token = await MoneyloverClient.getToken(email, password);
const client = new MoneyloverClient(token);

const wallets = await client.getWallets();
const txns = await client.getTransactions(walletId, '2026-01-01', '2026-04-30');
await client.addTransaction({ walletId, categoryId, amount: '50000', date: '2026-04-18' });
await client.editTransaction('txn-id', { amount: '60000', note: 'updated' });
await client.deleteTransaction('txn-id');

テスト

ユニットテスト

モック化されたユニットテスト — ライブ API 呼び出しは不要です:

npm test

統合テスト (mcp-tester)

mcp-tester は、ReAct エージェントベースの MCP テストフレームワークです。サーバーを起動し、自然言語プロンプトに応答してツールを呼び出すように LLM を駆動し、正しい引数で正しいツールが呼び出されたことをアサートします。

インストール

pipx install --index-url https://pypi.artifacts.furycloud.io/simple/ mcp-tester

設定

tests/mcp-tester/mcps.json — 資格情報を使用してローカルサーバーを指すようにします:

{
  "mcp-moneylover": {
    "command": "node",
    "args": ["/absolute/path/to/src/server.js"],
    "transport": "stdio",
    "env": {
      "EMAIL": "your@email.com",
      "PASSWORD": "your-password"
    }
  }
}

実行

mcp-tester run-tests \
  --mcps tests/mcp-tester/mcps.json \
  --model gpt-4o-mini \
  --concurrent-runs 3 \
  tests/mcp-tester/read-tools.yaml

結果

tests/mcp-tester/read-tools.yaml には、すべての読み取りツールをカバーする 25 個の統合テストが含まれています:

total 25, success 25, failures 0

テストを安定させるための重要な決定事項:

• 読み取りツールにトークンパラメータを含めない — オプションの token フィールドを公開すると、LLM がそこにウォレット ID を注入してしまうためです。サーバーは環境変数を介して自動的に認証を行います。

• 応答の切り詰め — 一部のエンドポイントは、共有 MoneyLover データベースから数十万件のレコードを返します。ツールは LLM のコンテキストを制御するために limit パラメータ (デフォルト: 20–100) を受け入れます。

• 辞書によるラップ — すべてのツール応答は JSON オブジェクトを返します（配列単体は返しません）。これにより、MCP フレームワークの検証を通過します。

書き込みツールのテスト (mcp-tester)

3 つの追加 YAML ファイルが、ウォレット、カテゴリ、取引の完全な CRUD ライフサイクルを 3 つの連続したフェーズでテストします。各フェーズで 3 つのリソースタイプすべてを同時に実行します。

フェーズを順番に実行します。各フェーズは前のフェーズに依存します:

# Phase 1: Create
mcp-tester run-tests --mcps tests/mcp-tester/mcps.json --model gpt-4o-mini --concurrent-runs 3 tests/mcp-tester/write-create.yaml

# Phase 2: Edit (after Phase 1 passes)
mcp-tester run-tests --mcps tests/mcp-tester/mcps.json --model gpt-4o-mini --concurrent-runs 3 tests/mcp-tester/write-edit.yaml

# Phase 3: Delete (after Phase 2 passes)
mcp-tester run-tests --mcps tests/mcp-tester/mcps.json --model gpt-4o-mini --concurrent-runs 3 tests/mcp-tester/write-delete.yaml

3 つのフェーズすべての結果:

Phase 1 (Create): total 3, success 3, failures 0
Phase 2 (Edit):   total 3, success 3, failures 0
Phase 3 (Delete): total 3, success 3, failures 0

書き込みツールテストの重要な設計決定:

• 変更前の探索 — 編集および削除テストでは、エージェントに対して、まず読み取りツール (get_wallets, get_categories, get_transactions) を呼び出して名前でターゲットを特定し、その後に変更ツールを呼び出すよう指示します。これは、ID が事前にわかっていない現実のエージェントの動作を反映しています。

• 書き込みツールのアサーションに args: !any を使用 — フレームワークは正確な引数の一致を要求します。書き込みツールは、エージェントが任意に含める可能性のあるオプションフィールド (icon, with など) を受け入れます。!any は、無害な追加要素で失敗することなく、ツールが呼び出され成功したことを検証します。読み取りツールのアサーションは、スキーマに LLM が自発的に追加するようなオプションフィールドがないため、正確な引数の一致を使用できます。

• 予測可能な識別子 — テストリソースは固定名 (MCP-Test-Wallet, MCP-Test-Category) と固定メモ (MCP test transaction) を使用するため、エージェントは編集および削除フェーズ中にテスト実行間で状態を共有することなく、名前でそれらを特定できます。

• 完全ペイロード編集のアサーション — edit_transaction は完全置換操作です。テストプロンプトは、エージェントに対して、まず既存の取引を取得 (get_transactions) し、現在のすべてのフィールド値を引き継ぎ、メモのみを変更するように指示します。これにより、ツールの説明で要求されるマルチステップの推論が検証されます。

セキュリティ上の注意

• 実際の資格情報やトークンをコミットしないでください。

• キャッシュされたトークンは ~/.moneylover-mcp/ に保存され、現在のユーザーのみに制限されます。

• キャッシュされたすべてのセッションを取り消すには、そのディレクトリを削除してください。