🚀 实际预算MCP服务器
实际预算MCP服务器用于将实际预算与Claude和其他大语言模型助手集成，让你可以通过自然语言与个人财务数据进行交互。
🚀 快速开始
实际预算MCP服务器允许你通过大语言模型，使用自然语言与来自实际预算的个人财务数据进行交互。它通过模型上下文协议（MCP）公开你的账户、交易和财务指标。
✨ 主要特性
资源
- 账户列表 - 浏览所有账户及其余额
- 账户详情 - 查看特定账户的详细信息
- 交易历史 - 访问包含完整细节的交易数据
工具
get-transactions- 按账户、日期、金额、类别或收款人检索和过滤交易spending-by-category- 生成按类型分类的支出明细monthly-summary- 获取每月的收入、支出和储蓄指标balance-history- 查看账户余额随时间的变化
提示
financial-insights- 根据你的财务数据生成洞察和建议budget-review- 分析你的预算合规情况并建议调整方案
📦 安装指南
前提条件
安装步骤
- 克隆仓库：
git clone https://github.com/s-stefanov/actual-mcp.git
cd actual-mcp
- 安装依赖：
npm install
- 构建服务器：
npm run build
- 配置环境变量（可选）：
# 实际预算数据目录的路径（默认：~/.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许可证。
🤝 贡献
欢迎贡献代码！请随时提交拉取请求。