关键词

个人财务管理LLM集成财务数据API预算管理自然语言交互

项目简介

Actual Budget MCP 服务器是一个后端应用，它将您的 Actual Budget 个人财务数据与 Claude 或其他支持 Model Context Protocol (MCP) 的大型语言模型助手连接起来。通过这个服务器，您可以使用自然语言查询您的账户余额、交易记录、消费模式，甚至进行预算分析和管理操作。

主要功能点

  • 财务资源访问:
    • 账户列表: 浏览所有账户及其余额。
    • 账户详情: 查看特定账户的详细信息。
    • 交易历史: 访问包含详细信息的交易数据。
  • 交易与账户管理工具:
    • 'get-transactions': 根据账户、日期、金额、类别或收款人检索和筛选交易。
    • 'get-accounts': 获取所有账户及其当前余额和ID列表。
    • 'balance-history': 查看账户余额随时间的变化。
  • 报告与分析工具:
    • 'spending-by-category': 按类别生成消费明细。
    • 'monthly-summary': 获取月度收入、支出和储蓄指标。
  • 类别管理工具: 'get-grouped-categories', 'create-category', 'update-category', 'delete-category', 'create-category-group', 'update-category-group', 'delete-category-group'。
  • 收款人管理工具: 'get-payees', 'create-payee', 'update-payee', 'delete-payee'。
  • 规则管理工具: 'get-rules', 'create-rule', 'update-rule', 'delete-rule'。
  • Prompt 模板:
    • 'financial-insights': 根据您的财务数据生成洞察和建议。
    • 'budget-review': 分析您的预算合规性并提出调整建议。

安装步骤

在开始之前，请确保您已安装 Node.js (v16 或更高版本) 和 Actual Budget。

  1. 克隆仓库:

    git clone https://github.com/sstefanov/actual-mcp.git
cd actual-mcp

  2. 安装依赖:

    npm install

  3. 构建服务器:

    npm run build

  4. 配置环境变量 (重要): 您需要配置服务器与 Actual Budget 数据通信所需的环境变量。这些变量可以在运行服务器时直接设置，或者放在 '.env' 文件中。

    • 'ACTUAL_DATA_DIR': 您的 Actual Budget 数据目录路径（例如：'/path/to/your/actual/data'）。如果使用远程 Actual 服务器，此项可选。
    • 'ACTUAL_SERVER_URL': 如果使用远程 Actual 服务器，请设置其 URL（例如：'https://your-actual-server.com'）。
    • 'ACTUAL_PASSWORD': 您的 Actual 服务器密码。如果服务器需要身份验证，此项必需。
    • 'ACTUAL_BUDGET_SYNC_ID': （可选）指定要使用的预算ID。
    • 'ACTUAL_BUDGET_ENCRYPTION_PASSWORD': （可选）如果本地加密预算数据需要不同于服务器认证的密码。

服务器配置（供MCP客户端使用）

MCP 客户端（如 Claude Desktop）需要知道如何启动并连接到 Actual Budget MCP 服务器。以下是您在 MCP 客户端配置中需要提供的关键信息：

  1. 服务器名称: 您可以为这个 MCP 服务器指定一个易于识别的名称，例如 'actualBudget'。
  2. 启动命令 (command):
    • 如果您在本地通过 Node.js 运行服务器，命令通常是 'node'。
    • 如果您使用 Docker 运行服务器，命令是 'docker'。
  3. 命令参数 (args):
    • 本地 Node.js 运行:
      • 如果您已经全局安装了 'actual-mcp' 包，可以使用 '['-y', 'actual-mcp', '--enable-write']'。
      • 如果您是从克隆的仓库本地运行，使用 '['/path/to/your/clone/build/index.js', '--enable-write']'。
    • Docker 运行:
      • 使用 '['run', '-i', '--rm', '-v', '/path/to/your/data:/data', '-e', 'ACTUAL_PASSWORD=your-password', '-e', 'ACTUAL_SERVER_URL=https://your-actual-server.com', '-e', 'ACTUAL_BUDGET_SYNC_ID=your-budget-id', 'sstefanov/actual-mcp:latest', '--enable-write']'。
      • 请将 '/path/to/your/data' 替换为您的 Actual Budget 数据目录路径。
      • 请将 'your-password', 'https://your-actual-server.com', 'your-budget-id' 替换为您的实际配置值。
    • '--enable-write' 参数是可选的，用于启用写入访问的工具（如创建、更新、删除类别/收款人/规则）。
  4. 环境变量 (env): 无论您是本地 Node.js 还是 Docker 运行，您都需要向 MCP 客户端提供服务器连接 Actual Budget 所需的环境变量。请根据您的 Actual Budget 设置，提供上述“配置环境变量”部分列出的 'ACTUAL_DATA_DIR'、'ACTUAL_SERVER_URL'、'ACTUAL_PASSWORD'、'ACTUAL_BUDGET_SYNC_ID' 等信息。

举例说明 (不含代码): 如果您使用 Claude Desktop 作为 MCP 客户端，您需要编辑其配置文件（通常在 macOS 上的 '~/Library/Application Support/Claude/claude_desktop_config.json' 或 Windows 上的 '%APPDATA%\Claude\claude_desktop_config.json'），在 'mcpServers' 部分添加一个名为 'actualBudget' 的配置项。在该配置项中，您会指定 'command'（例如 'node' 或 'docker'）以及一个 'args' 数组来传递启动服务器所需的命令行参数，例如服务器脚本路径和 '--enable-write' 选项。此外，您还需要在 'env' 对象中设置 'ACTUAL_DATA_DIR'、'ACTUAL_PASSWORD' 和 'ACTUAL_SERVER_URL' 等环境变量，以便服务器能够连接到您的 Actual Budget 数据。

配置完成后，请重新启动您的 MCP 客户端。

基本使用方法

连接成功后，您就可以通过自然语言向 LLM 助手提问，例如：

  • "我当前的账户余额是多少？"
  • "上个月我的消费按类别显示"
  • "一月份我在食品杂货上花了多少钱？"
  • "过去3个月我的储蓄率是多少？"
  • "分析我的预算并提出改进建议"

信息

分类

AI与计算

访问项目