AI导哈

个人财务数据MCP服务器

一个MCP服务器，使Claude.ai能够直接访问您的Actual Budget个人财务数据，提供账户、交易、预算等56种工具支持。

  • by Jacob-Tate
  • TypeScript
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 Jacob-Tate/actual-budget-mcp

使用说明

实际预算MCP服务器

一 MCP（模型上下文协议） 允许Claude.ai直接访问您的 实际预算 个人财务数据。

特性

  • 56工具 涵盖账户、交易、类别、收款人、自动化规则、收款人规则、预算、时间表、标签、分析、特别查询和名称到ID查找
  • OAuth 2.0 与Claude.ai的MCP集成兼容的身份验证
  • 单用户 设计——您的实际预算凭据是通过环境变量配置的，从不存储在令牌中
  • 无状态HTTP 运输与 StreamableHTTPServerTransport

可用工具

组 工具
账户 get-accounts, get-account-balance, create-account, update-account, close-account, reopen-account, delete-account
交易记录 get-transactions, import-transactions, add-transactions, update-transaction, delete-transaction
类别 get-categories, get-category-groups, create-category, update-category, delete-category, create-category-group, update-category-group, delete-category-group
收款人 get-payees, create-payee, update-payee, delete-payee, merge-payees
规则 get-rules, create-rule, update-rule, delete-rule
收款人规则 get-payee-rules, create-payee-rule, update-payee-rule, delete-payee-rule
预算 get-budget-months, get-budget-month, set-budget-amount, set-budget-carryover, hold-budget-for-next-month, reset-budget-hold, batch-set-budget-amounts, run-bank-sync, sync
时间表 get-schedules, create-schedule, update-schedule, delete-schedule
标签 get-tags, create-tag, update-tag, delete-tag
分析 monthly-summary, spending-by-category, budget-vs-actual, balance-history
查询 run-query
查找 get-id-by-name

金额 始终以毫为单位： 100 = $1.00, -4599 = -$45.99

示例提示

连接后，您可以问Claude以下问题：

支出和交易

  • “上个月我吃饭花了多少钱？”
  • “显示过去60天内亚马逊的所有费用”
  • “对我最近20笔未分类的交易进行分类”
  • “查找今年超过500美元的任何交易”

预算编制

  • “将我4月份的杂货预算设置为500美元”
  • “我如何对照本月的预算进行跟踪？”
  • “我在哪些方面超出了预算？”
  • “将本月预算金额复制到下个月”

财务健康状况

  • “在过去的6个月里，我的餐饮支出发生了什么变化？”
  • “我第一季度的收入与支出趋势是什么？”
  • “我经常超支哪些类别？”

账户和收款人

  • “我目前的支票账户余额是多少？”
  • “将所有‘全食超市’和‘全食市场’收款人合并在一起”
  • “显示我所有账户的净资产”

时间表和规则

  • “未来两周内有哪些经常性账单到期？”
  • “制定一项规则，始终将Spotify归类为娱乐”
  • “在1日设置每月1200美元的租金交易”

Docker 快速入门

# Pull and run
docker run -d \
  -p 3000:3000 \
  -v actual-data:/app/data \
  -e ACTUAL_SERVER_URL=https://your-actual-server.com \
  -e ACTUAL_SERVER_PASSWORD=your-actual-password \
  -e ACTUAL_SYNC_ID=your-sync-id \
  -e MCP_AUTH_PASSWORD=choose-a-strong-password \
  -e JWT_SECRET=$(openssl rand -hex 32) \
  -e BASE_URL=https://your-mcp-domain.com \
  ghcr.io/jacob-tate/actual-budget-mcp:latest

或者使用Docker Compose——请参阅 docker-compose.yml.

连接到Claude.ai

  1. 在Claude.ai中，请访问 设置→ 集成→ 添加MCP服务器
  2. 请输入您的服务器URL： https://your-mcp-domain.com/mcp
  3. 浏览器弹出窗口将打开——输入您的 MCP_AUTH_PASSWORD
  4. 完成--克劳德现在可以访问您的预算数据

环境变量

变量 必填 描述
ACTUAL_SERVER_URL ✅ 实际预算服务器的URL
ACTUAL_SERVER_PASSWORD ✅ 实际预算服务器密码
ACTUAL_SYNC_ID ✅ 预算同步ID（来自实际预算设置）
MCP_AUTH_PASSWORD ✅ OAuth浏览器弹出窗口中显示的密码
JWT_SECRET ✅ 签名令牌的随机字符串≥32个字符
BASE_URL ✅ 此MCP服务器的公共HTTPS URL
PORT -- HTTP端口（默认值： 3000)
ACTUAL_DATA_DIR -- 本地缓存目录（默认： ./data)
AUTH_DB_PATH -- OAuth令牌的SQLite数据库（默认值： {ACTUAL_DATA_DIR}/auth.db)

查找您的同步ID

在实际预算中： 设置→ 显示高级设置→ 同步ID

不使用Docker运行

需要 Node.js 22 LTS (better-sqlite3 无法在Node 24上编译）。

nvm use 22        # or: nvm install 22
npm install
cp .env.example .env
# edit .env with your values
npm run build
npm start

开发（热重新加载）：

npm run dev

类型检查 （缓慢——避免；使用 npm run build 相反）：

npm run typecheck

令牌撤销

要立即使令牌无效（例如怀疑泄漏、强制重新认证）：

# Revoke an access token (JWT)
curl -X POST https://your-mcp-domain.com/revoke \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=<access_token>"

# Revoke a refresh token (UUID)
curl -X POST https://your-mcp-domain.com/revoke \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=<refresh_token>"

总是回来 200 OK 每 RFC 7009 --即使令牌不存在。

要一次使所有令牌无效，请执行以下操作： 旋转 JWT_SECRET 在 .env 并重新启动。所有签发的JWT立即无法通过签名验证。

部署说明

  • 使用HTTPS暴露反向代理（nginx、Caddy）后面的端口3000
  • BASE_URL 必须是公共HTTPS URL——Claude.ai要求OAuth使用HTTPS
  • 这 /data 卷存储实际预算的本地缓存——挂载它以实现持久性
  • OAuth令牌在SQLite中持久化(./data/auth.db)--重新启动后仍能存活
  • 访问令牌在24小时后过期；刷新令牌持续90天，并自动轮换

项目结构

src/
├── config.ts              # Env var validation
├── index.ts               # Express app + startup
├── auth/
│   ├── db.ts              # SQLite singleton + schema init
│   ├── store.ts           # SQLite-backed OAuth state (tokens, clients)
│   ├── oauth.ts           # OAuthServerProvider + login form
│   └── middleware.ts      # Bearer token validation
├── actual/
│   └── client.ts          # @actual-app/api singleton
└── mcp/
    ├── server.ts
    └── tools/
        ├── accounts.ts
        ├── transactions.ts
        ├── categories.ts
        ├── payees.ts
        ├── payee-rules.ts
        ├── rules.ts
        ├── budget.ts
        ├── schedules.ts
        ├── tags.ts
        ├── analytics.ts
        ├── query.ts
        └── lookup.ts

相关 MCP