使用说明
实际预算MCP服务器
MCP（模型上下文协议）服务器，提供对 实际预算 API这允许LLM代理以编程方式与您的预算进行交互。
特性
-
动态API访问：工具公开整个实际预算API：
list_api_methods-通过文档发现可用方法call_api_method-动态调用任何API方法execute_aql_query-运行AQL（实际查询语言）查询get_aql_schema-获取表、字段和函数的AQL模式get_rules-以人类可读的DSL格式获取交易规则
-
55 API方法：完全访问所有实际预算操作：
- 预算管理（加载、同步、查看月份）
- 交易（CRUD、导入、批量操作）
- 账户、类别、收款人
- 规则（包括程序化规则执行）
- 日程表
- 银行同步
运作原理
此MCP服务器充当 客户端 到您的实际预算同步服务器。它使用 @actual-app/api 包连接到远程Actual实例，并通过MCP工具公开其功能。
┌─────────────────────────┐ ┌─────────────────────────┐
│ Your Machine │ HTTPS │ Remote Actual Server │
│ │◄───────►│ │
│ actual-mcp │ │ actual-sync-server │
│ (this MCP server) │ │ │
│ │ │ Stores master budget │
│ Local data cache │ │ data & handles sync │
│ ($XDG_DATA_HOME/ │ │ │
│ actual-mcp/) │ │ │
└─────────────────────────┘ └─────────────────────────┘
重要：The @actual-app/api 包维护一个 本地缓存 你的预算数据。加载预算时，它会从服务器下载数据并将其存储在本地。针对此本地缓存运行操作，以及 sync() 向服务器推送/从服务器拉取更改。
快速开始
直接从GitHub运行（无需安装）：
ACTUAL_SERVER_URL=http://localhost:5006 npx github:mweichert/actual-mcp
安装
对于当地发展：
git clone https://github.com/mweichert/actual-mcp.git
cd actual-mcp
npm install
npm run build
配置
环境变量
| 变量 | 必填 | 描述 |
|---|---|---|
ACTUAL_SERVER_URL |
是 | 实际预算同步服务器的URL（例如。， http://localhost:5006 或 https://actual.example.com) |
ACTUAL_PASSWORD |
否 | 服务器密码，如果您的服务器上启用了身份验证 |
ACTUAL_DATA_DIR |
否 | 本地预算缓存目录（见下文） |
ACTUAL_BUDGET_ID |
没有 | 启动时自动加载的预算ID。如果未设置，则必须调用 loadBudget() 手动 |
理解 ACTUAL_DATA_DIR
这 @actual-app/api 包需要一个本地目录来缓存预算数据。这是 不 远程服务器的数据目录——MCP服务器在这里存储其离线访问和性能预算的本地副本。
默认位置 （如下 XDG基本目录规范):
$XDG_DATA_HOME/actual-mcp/如果XDG_DATA_HOME已设置~/.local/share/actual-mcp/否则
以（权力）否决：设置 ACTUAL_DATA_DIR 要使用自定义位置，请执行以下操作：
ACTUAL_DATA_DIR=/path/to/cache npx github:mweichert/actual-mcp
码头工人：在Docker中运行时，挂载一个卷来持久化缓存：
docker run -v /host/path:/data -e ACTUAL_DATA_DIR=/data ...
用法
使用克劳德代码
添加到您的 .mcp.json:
{
"mcpServers": {
"actual-budget": {
"type": "stdio",
"command": "npx",
"args": ["github:mweichert/actual-mcp"],
"env": {
"ACTUAL_SERVER_URL": "https://actual.example.com",
"ACTUAL_PASSWORD": "your-password"
}
}
}
}
直接测试
ACTUAL_SERVER_URL=http://localhost:5006 npm start
工具参考
list_api_methods
了解可用的API方法。
参数：
category（可选）：按类别筛选(all,lifecycle,budget,transactions,accounts,categories,payees,rules,schedules,query,bank-sync)summary_only（可选）：仅返回每个类别的方法计数
例子：
{
"name": "list_api_methods",
"arguments": { "category": "accounts" }
}
call_api_method
调用任何实际预算API方法。
参数：
method（必填）：方法名称（例如。，getAccounts)params（可选）：方法参数为JSON对象
例子：
{
"name": "call_api_method",
"arguments": {
"method": "getAccounts",
"params": {}
}
}
工作流示例
- 列出预算:
call_api_method({ method: "getBudgets" }) - 负载预算:
call_api_method({ method: "loadBudget", params: { budgetId: "..." } }) - 获取帐户:
call_api_method({ method: "getAccounts" }) - 获取交易记录:
call_api_method({ method: "getTransactions", params: { accountId: "...", startDate: "2024-01-01", endDate: "2024-12-31" } }) - 同步更改:
call_api_method({ method: "sync" })
发展
# Install dependencies
npm install
# Build
npm run build
# Watch mode
npm run dev
许可证
麻省理工学院
