Monarch Money TypeScript SDK

Monarch Money TypeScript SDK

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

インストール

bun add monarchmoney

または

npm install monarchmoney

使用方法

ブラウザートークンを使ったクイックスタート

ブラウザーセッションのトークンを直接使うのが、最も簡単な始め方です。

import MonarchMoney from 'monarchmoney';

// You can get this token from your browser's localStorage or Cookies after logging in
// to Monarch Money on the web
const token = process.env.MONARCH_TOKEN;

// Create a client with the token
const mm = new MonarchMoney(token);

// Now you can use the API without logging in
const accounts = await mm.getAccounts();

標準の認証

トークンがない場合は、認証情報を使ってログインできます。

import MonarchMoney, { RequireMFAError } from 'monarchmoney';

// Create a new client
const mm = new MonarchMoney();

// Login using environment variables
const email = process.env.MONARCH_USER;
const password = process.env.MONARCH_PASSWORD;

if (!email || !password) {
  throw new Error('MONARCH_USER and MONARCH_PASSWORD environment variables must be set');
}

// Login
try {
  await mm.login({
    email,
    password
  });
} catch (error) {
  if (error instanceof RequireMFAError) {
    // Get MFA code from user
    const mfaCode = process.env.MONARCH_MFA || prompt('Enter MFA code:');
    
    await mm.authenticateWithMFA({
      email,
      password,
      mfaCode
    });
  } else {
    throw error;
  }
}

保存済みセッションの使用

セッションを保存して、後で使用できます。

// After logging in, save the session
mm.saveSession();

// Later, load the session
const mm = new MonarchMoney();
mm.loadSession();

// Now you can access data without logging in again
const accounts = await mm.getAccounts();

データへのアクセス

// Get accounts
const accounts = await mm.getAccounts();
console.log(accounts);

// Get transactions for current month
const today = new Date();
const firstDayOfMonth = new Date(today.getFullYear(), today.getMonth(), 1);
const lastDayOfMonth = new Date(today.getFullYear(), today.getMonth() + 1, 0);

const transactions = await mm.getTransactions({
  limit: 10,
  filters: {
    startDate: firstDayOfMonth.toISOString().split('T')[0],
    endDate: lastDayOfMonth.toISOString().split('T')[0]
  }
});
console.log(transactions);

// Get budgets
const budgets = await mm.getBudgets();
console.log(budgets);

// Get account holdings
const holdings = await mm.getAccountHoldings('account-id-here');
console.log(holdings);

サンプルの実行

同梱のサンプルを実行するには、次の 2 つの方法があります。

方法 1：ブラウザートークンを使用（最も簡単）

# Get the token from your browser after logging in to Monarch Money
# In Chrome: DevTools > Application > Storage > Local Storage > monarchmoney.com > find the auth token
export MONARCH_TOKEN="your-token-from-browser"

# Run the example
bun run example

方法 2：ユーザー名とパスワードを使用

# Set your credentials as environment variables
export MONARCH_USER="[email protected]"
export MONARCH_PASSWORD="your-password"
# Optional: Set MFA code if required
export MONARCH_MFA="123456"

# Run the example
bun run example

利用可能なメソッド

この SDK は Monarch Money データへの読み取り専用アクセスを提供します。

• getAccounts() - すべての口座を取得
• getAccountTypeOptions() - すべての口座タイプとサブタイプを取得
• getAccountHoldings(accountId) - 証券口座の保有証券を取得
• getAccountHistory(accountId) - 口座の日次履歴を取得
• getInstitutions() - リンク済みの金融機関を取得
• getBudgets(startDate, endDate) - 予算と実績額を取得
• getSubscriptionDetails() - 口座のサブスクリプション状態を取得
• getTransactionsSummary() - 取引の概要データを取得
• getTransactions(options) - 取引データを取得
• getTransactionCategories() - 取引カテゴリを取得
• getTransactionCategoryGroups() - 取引カテゴリグループを取得
• getTransactionDetails(transactionId) - 取引の詳細を取得
• getTransactionSplits(transactionId) - 取引の分割情報を取得
• getTransactionTags() - 取引タグを取得
• getCashflow(options) - キャッシュフローデータを取得
• getCashflowSummary(options) - キャッシュフローの概要を取得
• getRecurringTransactions(startDate, endDate) - 定期取引を取得

AI エージェント向け MCP サーバー

この SDK には、AI エージェントが Monarch Money と連携できる Model Context Protocol（MCP）サーバーが含まれています。MCP サーバーは、口座、取引、予算などを照会するためのツールを提供します。

MCP サーバーを起動するには：

# Set up authentication via environment variables
export MONARCH_TOKEN="your-token-from-browser"

# Start the MCP server
bun run mcp

MCP サーバーは MONARCH_TOKEN 環境変数を使って自動的に認証し、次のツールを提供します。

• check_authentication - 認証済みかどうかを確認
• get_accounts - すべての口座を取得
• get_account_holdings - 口座の保有証券を取得
• get_account_history - 口座の履歴を取得
• get_transactions - フィルターを指定して取引を取得
• get_transaction_categories - 取引カテゴリを取得
• get_budgets - 指定した期間の予算を取得
• get_cashflow - フィルターを指定してキャッシュフローデータを取得

Claude Desktop の設定

Claude Desktop で使用するには、次の内容を Claude Desktop の設定ファイル（~/Library/Application Support/Claude/claude_desktop_config.json にあります）に追加します。

{
  "mcpServers": {
    "monarchMoney": {
      "command": "bun",
      "args": ["run", "mcp"],
      "env": {
        "MONARCH_TOKEN": "your-monarch-token-here"
      },
      "cwd": "/path/to/your/monarch-ts"
    }
  }
}

/path/to/your/monarch-ts をプロジェクトディレクトリの実際のパスに、your-monarch-token-here をブラウザーから取得した Monarch Money のトークンに置き換えてください。

ライセンス

MIT