Actual MCP

🚀 实际预算MCP服务器

实际预算MCP服务器用于将实际预算与Claude和其他大语言模型助手集成，让你可以通过自然语言与个人财务数据进行交互。

🚀 快速开始

实际预算MCP服务器允许你通过大语言模型，使用自然语言与来自实际预算的个人财务数据进行交互。它通过模型上下文协议（MCP）公开你的账户、交易和财务指标。

✨ 主要特性

资源

• 账户列表 - 浏览所有账户及其余额
• 账户详情 - 查看特定账户的详细信息
• 交易历史 - 访问包含完整细节的交易数据

工具

• get-transactions - 按账户、日期、金额、类别或收款人检索和过滤交易
• spending-by-category - 生成按类型分类的支出明细
• monthly-summary - 获取每月的收入、支出和储蓄指标
• balance-history - 查看账户余额随时间的变化

提示

• financial-insights - 根据你的财务数据生成洞察和建议
• budget-review - 分析你的预算合规情况并建议调整方案

📦 安装指南

前提条件

• Node.js（v16或更高版本）
• 已安装并配置好实际预算
• Claude桌面版或其他支持MCP的客户端

安装步骤

1. 克隆仓库：

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

2. 安装依赖：

npm install

3. 构建服务器：

npm run build

4. 配置环境变量（可选）：

# 实际预算数据目录的路径（默认：~/.actual）
export ACTUAL_DATA_DIR="/path/to/your/actual/data"

# 如果使用远程实际预算服务器
export ACTUAL_SERVER_URL="https://your-actual-server.com"
export ACTUAL_PASSWORD="your-password"

# 要使用的特定预算（可选）
export ACTUAL_BUDGET_SYNC_ID="your-budget-id"

💻 使用示例

与Claude桌面版配合使用

要在Claude桌面版中使用此服务器，需将其添加到Claude配置中：

在MacOS上：

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

在Windows上：

code %APPDATA%\Claude\claude_desktop_config.json

在配置中添加以下内容：

{
  "mcpServers": {
    "actualBudget": {
      "command": "npx",
      "args": ["-y", "actual-mcp"],
      "env": {
        "ACTUAL_DATA_DIR": "/path/to/your/actual/data",
        "ACTUAL_PASSWORD": "your-password",
        "ACTUAL_SERVER_URL": "https://your-actual-server.com",
        "ACTUAL_BUDGET_SYNC_ID": "your-budget-id"
      }
    }
  }
}

{
  "mcpServers": {
    "actualBudget": {
      "command": "docker",
      "args": ["run", "-it", "--rm", "-p", "3000:3000", "sstefanov/actual-mcp:latest"],
      "env": {
        "ACTUAL_DATA_DIR": "/path/to/your/actual/data",
        "ACTUAL_PASSWORD": "your-password",
        "ACTUAL_SERVER_URL": "https://your-actual-server.com",
        "ACTUAL_BUDGET_SYNC_ID": "your-budget-id"
      }
    }
  }
}

保存配置后，重启Claude桌面版。

示例查询

连接成功后，你可以向Claude提出以下问题：

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

🔧 技术细节

开发

若要在开发过程中实现自动重建，可以运行：

npm run watch

测试与实际预算的连接

要验证服务器是否能连接到你的实际预算数据，可以运行：

node build/index.js --test-resources

调试

由于MCP服务器通过标准输入输出进行通信，调试可能具有一定挑战性。你可以使用MCP检查器：

npx @modelcontextprotocol/inspector node build/index.js

项目结构

• index.ts - 主服务器实现
• types.ts - API响应和参数的类型定义
• prompts.ts - 用于大语言模型交互的提示模板
• utils.ts - 用于日期格式化等的辅助函数

📄 许可证

本项目采用MIT许可证。

🤝 贡献

欢迎贡献代码！请随时提交拉取请求。