Monarch Money TypeScript SDK

一个用于访问Monarch Money数据的TypeScript库。

安装

bun add monarchmoney

或

npm install monarchmoney

使用

快速开始：浏览器令牌

最简单的开始方式是直接使用浏览器会话中的令牌：

import MonarchMoney from 'monarchmoney';

// 你可以从登录到Monarch Money网页后的浏览器localStorage或Cookies中获取这个令牌
const token = process.env.MONARCH_TOKEN;

// 使用令牌创建客户端
const mm = new MonarchMoney(token);

// 现在你可以无需登录就使用API
const accounts = await mm.getAccounts();

标准认证

如果你没有令牌，可以使用凭证登录：

import MonarchMoney, { RequireMFAError } from 'monarchmoney';

// 创建新的客户端
const mm = new MonarchMoney();

// 使用环境变量登录
const email = process.env.MONARCH_USER;
const password = process.env.MONARCH_PASSWORD;

if (!email || !password) {
  throw new Error('必须设置MONARCH_USER和MONARCH_PASSWORD环境变量');
}

// 登录
try {
  await mm.login({
    email,
    password
  });
} catch (error) {
  if (error instanceof RequireMFAError) {
    // 获取用户输入的MFA代码
    const mfaCode = process.env.MONARCH_MFA || prompt('请输入MFA代码：');
    
    await mm.authenticateWithMFA({
      email,
      password,
      mfaCode
    });
  } else {
    throw error;
  }
}

使用保存的会话

你可以保存会话以备后用：

// 登录后保存会话
mm.saveSession();

// 后续加载会话
const mm = new MonarchMoney();
mm.loadSession();

// 现在你可以无需再次登录就能访问数据
const accounts = await mm.getAccounts();

访问数据

// 获取账户
const accounts = await mm.getAccounts();
console.log(accounts);

// 获取当前月份的交易记录
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);

// 获取预算
const budgets = await mm.getBudgets();
console.log(budgets);

// 获取账户持仓
const holdings = await mm.getAccountHoldings('account-id-here');
console.log(holdings);

运行示例

要运行包含的示例，你有两个选项：

选项1：使用浏览器令牌（最简单）

# 在登录到Monarch Money后从浏览器获取令牌
# 在Chrome中：开发者工具 > 应用 > 存储 > Local Storage > monarchmoney.com > 找到auth令牌
export MONARCH_TOKEN="your-token-from-browser"

# 运行示例
bun run example

选项2：使用用户名/密码

# 将你的凭证设置为环境变量
export MONARCH_USER="your.email@example.com"
export MONARCH_PASSWORD="your-password"
# 可选：如果需要，设置MFA代码
export MONARCH_MFA="123456"

# 运行示例
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) - 获取定期交易

MCP服务器用于AI代理

此SDK包括一个Model Context Protocol (MCP)服务器，允许AI代理与Monarch Money进行交互。MCP服务器提供了查询账户、交易、预算等功能的工具。

要启动MCP服务器：

# 通过环境变量设置认证
export MONARCH_TOKEN="your-token-from-browser"

# 启动MCP服务器
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中使用此SDK，请在Claude Desktop配置文件（位于~/Library/Application Support/Claude/claude_desktop_config.json）中添加以下内容：

{
  "mcpServers": {
    "monarchMoney": {
      "command": "b