mcpField
M
monarchmoney

monarchmoney

ローカル
github.com/hakimelek金融データ233 週間前に更新
リポジトリ

monarchmoney について

monarchmoneyは、Monarch Moneyの金融データにアクセスするNode.js/TypeScriptライブラリ兼MCPサーバーです。アカウント、取引、予算、キャッシュフローを型付き操作で扱い、読み取りと書き込みの両方に対応します。

主な機能

  1. 01アカウント・取引向けの型付きAPIメソッド
  2. 02予算・キャッシュフロー・保有資産・残高
  3. 03メールOTPとMFAの認証フロー
  4. 04セッショントークンの保存と再利用
  5. 05自動ページネーションと一時エラーの再試行
  6. 06読み書きに対応する30個のMCPツール

活用シーン

  1. 01アプリケーションでの金融データ取得
  2. 02MCPクライアントを使った取引・予算・キャッシュフロー確認
  3. 03AIエージェントによる取引やアカウント設定の更新

MCP 対応

組み込みMCPサーバーは、Monarch Moneyデータを読み書きする30個のツールを公開します。MCPクライアントからアカウント、取引、予算、キャッシュフロー、および対応する変更操作を利用できます。

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定
{
  "mcpServers": {
    "hakimelek-monarchmoney": {
      "command": "npx",
      "args": [
        "-y",
        "@hakimelek/monarchmoney"
      ],
      "env": {
        "MONARCH_TOKEN": "<MONARCH_TOKEN>"
      }
    }
  }
}
起動コマンドnpx -y @hakimelek/monarchmoney
設定が必要な環境変数
MONARCH_TOKENシークレットYour Monarch Money auth token. Obtain by logging in with the library and saving mm.token.

ローカルサーバーにはマシン上の実行環境（Node.js 18 以上など）が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ
npm@hakimelek/monarchmoney0.3.1

ツール

30

掲載時のツール一覧 · 2 週間前に更新

このツールにパラメーターはありません。

詳細

Monarch Money（Node.js）

Monarch Money のデータにアクセスするための Node.js/TypeScript ライブラリです。

免責事項： このプロジェクトは非公式であり、Monarch Money とは提携していません。

インストール

npm install @hakimelek/monarchmoney

Node.js 18 以降が必要です（ネイティブの fetch と AbortSignal.timeout を使用します）。

クイックスタート

import {
  MonarchMoney,
  EmailOtpRequiredException,
  RequireMFAException,
} from "@hakimelek/monarchmoney";

const mm = new MonarchMoney();

try {
  await mm.login("[email protected]", "password");
} catch (e) {
  if (e instanceof EmailOtpRequiredException) {
    // Monarch sent a verification code to your email
    const code = await promptUser("Enter the code from your email:");
    await mm.submitEmailOtp("[email protected]", "password", code);
  } else if (e instanceof RequireMFAException) {
    // TOTP-based MFA is enabled on the account
    await mm.multiFactorAuthenticate("[email protected]", "password", "123456");
  }
}

// Fetch data — fully typed responses
const { accounts } = await mm.getAccounts();
console.log(accounts[0].displayName, accounts[0].currentBalance);

認証

Monarch の API では、MFA が無効になっている場合でも、新しいデバイス／セッションではメール認証（OTP）が必要です。このライブラリでは、アプリが適切に対応できるよう、例外の種類を明確に分けています。

メール OTP 認証を使ったログイン
try {
  await mm.login(email, password);
} catch (e) {
  if (e instanceof EmailOtpRequiredException) {
    // A code was sent to the user's email — prompt them for it
    const code = await yourApp.promptForEmailCode();
    await mm.submitEmailOtp(email, password, code);
  }
}
MFA シークレットキーを使う場合（TOTP を自動化）
await mm.login("email", "password", {
  mfaSecretKey: "YOUR_BASE32_SECRET",
});

MFA シークレットは、Monarch Money の Settings > Security > Enable MFA にある「Two-factor text code」です。

セッションの永続化とトークンの再利用

ログインが成功した後（メール OTP を含む）は、毎回再認証せずに済むよう、トークンを保存できます。

// Save token after login
mm.saveSession(); // writes to .mm/mm_session.json (mode 0o600)

// Next time, login() loads the saved session automatically
await mm.login(email, password); // uses saved token, no network call

// Or pass the token directly (skip login entirely)
const mm = new MonarchMoney({ token: "your-saved-token" });

mm.saveSession();          // save to disk
mm.loadSession();          // load from disk
mm.deleteSession();        // remove the file
mm.setToken("...");        // set token programmatically
対話型 CLI
await mm.interactiveLogin(); // prompts for email, password, email OTP or MFA code

API

すべてのメソッドは型付きレスポンスを返します。エディターで任意のメソッドにカーソルを合わせると、JSDoc と型情報をすべて確認できます。

読み取りメソッド
メソッド戻り値説明
getAccounts()GetAccountsResponseリンク済みのすべての口座
getAccountTypeOptions()GetAccountTypeOptionsResponse利用可能な口座の種類／サブタイプ
getRecentAccountBalances(startDate?)GetRecentAccountBalancesResponse日次残高（デフォルト：過去 31 日間）
getAccountSnapshotsByType(startDate, timeframe)GetSnapshotsByAccountTypeResponse種類別のスナップショット（"year" ／ "month"）
getAggregateSnapshots(options?)GetAggregateSnapshotsResponse時系列の純資産総額
getAccountHoldings(accountId)GetAccountHoldingsResponse証券口座の保有証券
getAccountHistory(accountId)AccountHistorySnapshot[]日次残高の履歴
getInstitutions()GetInstitutionsResponseリンク済みの金融機関
getBudgets(startDate?, endDate?)GetBudgetsResponse実績を含む予算（デフォルト：先月から来月まで）
getSubscriptionDetails()GetSubscriptionDetailsResponseプランの状態（トライアル、プレミアムなど）
getTransactionsSummary()GetTransactionsSummaryResponse集計サマリー
getTransactions(options?)GetTransactionsResponse詳細な絞り込みが可能な取引
getAllTransactions(options?)Transaction[]条件に一致するすべての取引（ページネーションを自動処理）
getTransactionPages(options?)AsyncGenerator<Transaction[]>ページを順次返す非同期ジェネレーター
getTransactionCategories()GetTransactionCategoriesResponseすべてのカテゴリ
getTransactionCategoryGroups()GetTransactionCategoryGroupsResponseカテゴリグループ
getTransactionDetails(id)typed response単一の取引の詳細
getTransactionSplits(id)typed response取引の分割
getTransactionTags()GetTransactionTagsResponseすべてのタグ
getCashflow(options?)GetCashflowResponseカテゴリ、グループ、加盟店別のキャッシュフロー
getCashflowSummary(options?)GetCashflowSummaryResponse収入、支出、貯蓄、貯蓄率
getRecurringTransactions(start?, end?)GetRecurringTransactionsResponse今後の定期取引
isAccountsRefreshComplete(ids?)boolean更新状況を確認
書き込みメソッド
メソッド戻り値説明
createManualAccount(params)CreateManualAccountResponse手動アカウントを作成
updateAccount(id, updates)UpdateAccountResponseアカウントの設定／残高を更新
deleteAccount(id)DeleteAccountResponseアカウントを削除
requestAccountsRefresh(ids)boolean更新を開始（非ブロッキング）
requestAccountsRefreshAndWait(opts?)boolean更新し、完了するまでポーリング
createTransaction(params)CreateTransactionResponse取引を作成
updateTransaction(id, updates)UpdateTransactionResponse取引を更新
deleteTransaction(id)boolean取引を削除
updateTransactionSplits(id, splits)UpdateTransactionSplitResponse分割を管理
createTransactionCategory(params)CreateCategoryResponseカテゴリを作成
deleteTransactionCategory(id, moveTo?)booleanカテゴリを削除
deleteTransactionCategories(ids)(boolean | Error)[]一括削除
createTransactionTag(name, color)CreateTransactionTagResponseタグを作成
setTransactionTags(txId, tagIds)SetTransactionTagsResponse取引にタグを設定
setBudgetAmount(params)SetBudgetAmountResponse予算を設定／クリア
uploadAccountBalanceHistory(id, csv)void残高履歴の CSV をアップロード

エラー処理

import {
  MonarchMoneyError,          // base class for all errors
  EmailOtpRequiredException,  // email verification code needed — call submitEmailOtp()
  RequireMFAException,        // TOTP MFA required — call multiFactorAuthenticate()
  LoginFailedException,       // bad credentials or auth error (includes .statusCode)
  RequestFailedException,     // API/GraphQL failure (includes .statusCode, .graphQLErrors)
} from "@hakimelek/monarchmoney";

try {
  await mm.login(email, password);
} catch (e) {
  if (e instanceof EmailOtpRequiredException) {
    // e.code === "EMAIL_OTP_REQUIRED"
    // Prompt user for the code sent to their email
    const code = await getCodeFromUser();
    await mm.submitEmailOtp(email, password, code);
  } else if (e instanceof RequireMFAException) {
    // e.code === "MFA_REQUIRED"
    // Prompt for TOTP code or use mfaSecretKey
  } else if (e instanceof LoginFailedException) {
    // e.code === "LOGIN_FAILED", e.statusCode
    console.error("Login failed:", e.message);
  }
}

try {
  await mm.getAccounts();
} catch (e) {
  if (e instanceof RequestFailedException) {
    console.error(e.statusCode);     // HTTP status, if applicable
    console.error(e.graphQLErrors);  // GraphQL errors array, if applicable
    console.error(e.code);           // "HTTP_ERROR" | "REQUEST_FAILED"
  }
}

設定

const mm = new MonarchMoney({
  sessionFile: ".mm/mm_session.json", // session file path
  timeout: 10,                        // API timeout in seconds
  token: "pre-existing-token",        // skip login
  retry: {
    maxRetries: 3,                    // retry on 429/5xx (default: 3, set 0 to disable)
    baseDelayMs: 500,                 // base delay with exponential backoff + jitter
  },
  rateLimit: {
    requestsPerSecond: 10,            // token-bucket throttle (default: 0 = unlimited)
  },
});

mm.setTimeout(30); // change timeout later

再試行機能は、一時的な障害（429 Too Many Requests、500、502、503、504）に対して、指数バックオフとジッターを使用して自動的に処理します。429 応答では Retry-After ヘッダーが尊重されます。

自動ページネーション

getTransactions() は単一のページを返します。大規模なデータセットの場合は、自動ページネーションヘルパーを使用してください。

// Async generator — yields one page at a time (memory-efficient)
for await (const page of mm.getTransactionPages({ startDate: "2025-01-01", endDate: "2025-12-31" })) {
  for (const tx of page) {
    console.log(tx.merchant?.name, tx.amount);
  }
}

// Or collect everything into a flat array
const all = await mm.getAllTransactions({
  startDate: "2025-01-01",
  endDate: "2025-12-31",
  pageSize: 100, // transactions per page (default: 100)
});
console.log(`${all.length} total transactions`);

どちらのメソッドも、getTransactions() と同じフィルターオプション（期間、カテゴリ、アカウント、タグなど）を受け付けます。

更新の進行状況

onProgress コールバックを使用して、アカウント更新の進行状況を追跡します。

await mm.requestAccountsRefreshAndWait({
  timeout: 300,
  delay: 10,
  onProgress: ({ completed, total, elapsedMs }) => {
    console.log(`${completed}/${total} accounts refreshed (${(elapsedMs / 1000).toFixed(0)}s)`);
  },
});

MCP サーバー（AI エージェント連携）

このパッケージには、30 個のツールを備えた組み込みのModel Context Protocolサーバーが含まれており、Monarch Money のデータを Claude Desktop、Cursor、および MCP 互換のクライアントなどの AI アシスタントから利用できます。

セットアップ

  1. ライブラリを使ってログインし（認証を参照）、mm.token を保存して Monarch Money の認証トークンを取得します。

  2. MCP クライアントの設定に追加します（例：Claude Desktop の claude_desktop_config.json）。

{
  "mcpServers": {
    "monarch-money": {
      "command": "npx",
      "args": ["@hakimelek/monarchmoney"],
      "env": {
        "MONARCH_TOKEN": "your-token-here"
      }
    }
  }
}

または、直接実行します。

MONARCH_TOKEN=your-token npx @hakimelek/monarchmoney
利用可能なツール

読み取り（18 個のツール）： get_accounts、get_account_holdings、get_account_history、get_account_type_options、get_recent_account_balances、get_aggregate_snapshots、get_institutions、get_budgets、get_subscription_details、get_transactions、get_transactions_summary、get_transaction_details、get_transaction_categories、get_transaction_category_groups、get_transaction_tags、get_cashflow、get_cashflow_summary、get_recurring_transactions

書き込み（12 個のツール）： create_transaction、update_transaction、delete_transaction、create_manual_account、update_account、delete_account、refresh_accounts、is_refresh_complete、set_budget_amount、create_transaction_tag、set_transaction_tags、create_transaction_category

すべてのツールには説明付きの型指定パラメーターがあるため、AI エージェントは渡す引数を正確に把握できます。

プロジェクト構成

src/
  index.ts      — public exports
  client.ts     — MonarchMoney class with all API methods
  mcp.ts        — MCP server (30 tools for AI agents)
  errors.ts     — error classes (MonarchMoneyError hierarchy)
  endpoints.ts  — API URL constants
  queries.ts    — all GraphQL query/mutation strings
  types.ts      — TypeScript interfaces for all API responses

テスト

npm test              # run tests once
npm run test:watch    # run tests in watch mode
npm run test:coverage # run with coverage report

テストにはVitestを使用しており、実際の API 認証情報は不要です（必要な箇所では fetch をモックします）。

API 接続をテストする（稼働中の api.monarch.com に対して実行）：

npm run build

# Login with email + password (will prompt for email OTP code if required)
[email protected] MONARCH_PASSWORD=yourpassword npm run test:connection

# Use a saved token (skips login)
MONARCH_TOKEN=your-token npm run test:connection -- --token

.env ファイルにこれらを設定すると便利です（.env.example を参照）。

よくある質問

Google 経由で Monarch にログインしている場合、どうすれば使えますか？

Settings > Security で Monarch アカウントにパスワードを設定し、そのパスワードをこのライブラリで使用してください。

ログインするたびに、Monarch からメールコードを求められるのはなぜですか？

Monarch では、新しいデバイスや認識されていないデバイスに対してメール認証が必要です。ログイン後、mm.saveSession() でセッショントークンを保存するか、mm.token を保存してください。以降の実行では再認証なしで利用できます。

このライブラリの比較

Monarch Money には、非公式の統合がいくつかあります。@hakimelek/monarchmoney の位置づけは以下のとおりです。

全体像
@hakimelek/monarchmoneymonarch-money-api (pbassham)monarchmoney (keithah)monarchmoney (hammem)
プラットフォームNode.js / TypeScriptNode.js / JavaScriptNode.js / TypeScriptPython
npm の週間ダウンロード数—~440~130該当なし（pip：約103K／月）
実行時依存関係1（speakeasy）573
TypeScript 型定義完全（すべてのレスポンス）なしあり該当なし
メール OTP フローありなしなしなし
MFA / TOTPありありありあり
セッションの永続化あり（権限 0o600）ありあり（AES-256）あり
対話型 CLI ログインありありありあり
HTTP クライアントネイティブの fetchnode-fetchnode-fetch + graphql-requestaiohttp
エラー階層型付き例外 4 種汎用エラーをスロー汎用エラーをスロー例外 1 種
読み取りメソッド2015~20~16
書き込みメソッド149~12~10
レート制限ありなしありなし
バックオフ付き再試行ありなしありなし
自動ページネーションありなしなしなし
CJS + ESM の両対応ありなしありなし
更新進捗イベントありなしなしなし
組み込み MCP サーバーあり（ツール 30 個）なしなしなし
このライブラリの強み

最小限の依存関係。 JS／TS の代替ライブラリでは実行時依存関係が 5～7 個あるのに対し、こちらは 1 個です。ネイティブの fetch を使用するため、Node 18 以降では HTTP ポリフィルが不要です。

メール OTP に対応。 Monarch では現在、MFA がオフの場合でも、認識されていないデバイスに対してメール認証が必要です。EmailOtpRequiredException → submitEmailOtp() の一連のフローに対応している Node.js ライブラリはこれだけです。この機能がなければ、新しい環境から初めてログインする際に自動化スクリプトが失敗します。

すべてに型定義を用意。 すべての API レスポンスに専用の TypeScript インターフェースがあり、アカウント、取引、保有資産、キャッシュフロー、予算、定期項目、変更処理を網羅する 50 種類以上の型をエクスポートしています。monarch-money-api パッケージには型定義がまったくありません。

構造化されたエラー処理。 エラーコードとステータスコードを備えた 4 種類の異なる例外クラス（LoginFailedException、RequireMFAException、EmailOtpRequiredException、RequestFailedException）があります。競合ライブラリは汎用エラーまたは文字列をスローします。

より幅広い書き込み機能。 updateTransaction()、setBudgetAmount()、uploadAccountBalanceHistory()、getCashflow()、getCashflowSummary()、getRecurringTransactions() が含まれています。これらはすべて monarch-money-api にはありません。

シンプルでフラットな API。 クラスは 1 つで、メソッドを直接呼び出せます。サブオブジェクトや、覚える必要のある詳細度レベルはありません。MonarchMoney をインポートしてメソッドを呼び出せば、型付きの結果を取得できます。

コントリビュート

コントリビュートを歓迎します。TypeScript が問題なくコンパイルできること（npm run build）と、テストが通ること（npm test）を確認してください。

ライセンス

MIT

コメント

Markdown 対応

MCP は初めてですか？

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。