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);

运行示例

运行随附示例有两种方式：

选项 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 Agent 的 MCP 服务

此 SDK 包含一个模型上下文协议（MCP）服务，可让 AI Agent 与 Monarch Money 交互。该 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