에이전트 강화
게시자의 자체 명령입니다. PlugMCP 엔드포인트가 아닙니다.
Host a copy with our keys and logs.
npx -y [email protected]Claude Code에는 로컬 명령용 설치 링크가 없습니다. 아래 명령을 복사해 터미널에서 실행합니다.
claude mcp add actual-mcp -- npx -y actual-mcp@1.15.1터미널에서 실행합니다.
{ "mcpServers": { "actual-mcp": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}claude_desktop_config.json
원격 URL인가요, 내 컴퓨터에서 실행하는 명령인가요? 두 설치 방식의 차이
PlugMCP에서 실행
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
실행게시자 제공
MCP server for integrating Actual Budget with Claude and other LLM assistants.
The Actual Budget MCP Server allows you to interact with your personal financial data from Actual Budget using natural language through LLMs. It exposes your accounts, transactions, and financial metrics through the Model Context Protocol (MCP).
Actual Budget MCP server exposing API functionality
get-transactions - Retrieve and filter transactions by account, date, amount, category, or payeecreate-transaction - Create a new transaction in an account with optional category, payee, and notesupdate-transaction - Update an existing transaction with new category, payee, notes, or amountget-accounts - Retrieve a list of all accounts with their current balance and IDbalance-history - View account balance changes over timespending-by-category - Generate spending breakdowns categorized by typemonthly-summary - Get monthly income, expenses, and savings metricsbudget-vs-actual - Compare budgeted amounts against actual spending per categorynet-worth - Track assets, liabilities, and net worth across all accounts over timecategory-trends - See how spending in each category moves month over month, with trend directionspending-by-payee - Rank payees by how much was spent with (or received from) each onecash-flow - Report income, expenses, and net cash flow per month or weekThe five tools above return JSON rather than markdown, so amounts stay machine-readable. Every amount is an integer number of cents, and each response carries an
amountsInfield describing the sign conventions it uses.
get-custom-reports - Retrieve every saved custom report from the Reports sectioncreate-custom-report - Create a saved custom reportupdate-custom-report - Update fields on a saved custom report, leaving the rest unchangeddelete-custom-report - Delete a saved custom reportget-dashboards - Retrieve every dashboard page and the widgets laid out on itadd-dashboard-widget - Add a widget to a dashboard pageupdate-dashboard-widget - Update a widget's configuration, position, or sizeremove-dashboard-widget - Remove a widget from its pageorganize-dashboard - Reposition and resize several widgets at oncecreate-dashboard-page / rename-dashboard-page / delete-dashboard-page - Manage dashboard pagesget-grouped-categories - Retrieve a list of all category groups with their categoriescreate-category - Create a new category within a category groupupdate-category - Update an existing category's name or groupdelete-category - Delete a categorycreate-category-group - Create a new category groupupdate-category-group - Update a category group's namedelete-category-group - Delete a category groupget-payees - Retrieve a list of all payees with their detailscreate-payee - Create a new payeeupdate-payee - Update an existing payee's detailsdelete-payee - Delete a payeemerge-payees - Merge duplicate payees into a single target payeeget-rules - Retrieve a list of all transaction rulescreate-rule - Create a new transaction rule with conditions and actionsupdate-rule - Update an existing transaction ruledelete-rule - Delete a transaction rulefinancial-insights - Generate insights and recommendations based on your financial databudget-review - Analyze your budget compliance and suggest adjustmentsPull the latest docker image:
docker pull sstefanov/actual-mcp:latest
git clone https://github.com/s-stefanov/actual-mcp.git
cd actual-mcp
npm install
npm run build
docker build -t <local-image-name> .
# Path to your Actual Budget data directory (default: ~/.actual)
export ACTUAL_DATA_DIR="/path/to/your/actual/data"
# If using a remote Actual server
export ACTUAL_SERVER_URL="https://your-actual-server.com"
export ACTUAL_PASSWORD="your-password"
# Specific budget to use (optional)
export ACTUAL_BUDGET_SYNC_ID="your-budget-id"
# How long downloaded data stays fresh before the server re-syncs, in ms
# (default: 60000). Use 0 to sync before every call, or -1 to never sync.
export ACTUAL_SYNC_TTL_MS="60000"
Optional: separate encryption budget password
If your Actual setup requires a different password to unlock the local/encrypted budget data than the server authentication password, you can set ACTUAL_BUDGET_ENCRYPTION_PASSWORD in addition to ACTUAL_PASSWORD.
# If server auth and encryption/unlock use different passwords
export ACTUAL_BUDGET_ENCRYPTION_PASSWORD="your-encryption-password"
Optional: OpenID servers (session token auth)
If your Actual server uses OpenID login (for example Google) with ACTUAL_OPENID_ENFORCE=true, password login is disabled, so ACTUAL_PASSWORD can't be used. Instead, sign in to Actual in a browser and pass the resulting session token. It takes precedence over ACTUAL_PASSWORD.
export ACTUAL_SERVER_URL="https://your-actual-server.com"
export ACTUAL_SESSION_TOKEN="your-session-token"
To find the token, sign in to Actual in your browser, open DevTools, and go to Application → IndexedDB → actual → asyncStorage. The value of the user-token key is your session token. It's a UUID (e.g. 3f2b8c1e-9a4d-4e7b-8c2a-1d5e6f7a8b9c), not a long JWT-style bearer token. You can check it with curl -H "X-ACTUAL-TOKEN: <token>" https://your-actual-server.com/account/validate, which should return "validated": true. Treat it like a password: it grants full access to your budgets. How long it stays valid depends on the server's ACTUAL_TOKEN_EXPIRATION setting. If it is invalid or expired, the MCP server still starts, but tool calls fail with Authentication failed: invalid or expired session token, because the server connects to Actual on the first request (--test-resources reports the error immediately). Sign in again, replace the token, and restart the MCP server.
The server keeps one shared Actual connection for its entire lifetime and serializes budget operations through it. Downloaded data is re-synced when it exceeds the ACTUAL_SYNC_TTL_MS freshness window. In both stdio and HTTP modes, SIGINT and SIGTERM drain in-flight work before the server shuts down. Actual is no longer initialized and shut down for each tool call.
To use this server with Claude Desktop, add it to your Claude configuration:
On MacOS:
code ~/Library/Application\ Support/Claude/claude_desktop_config.json
On Windows:
code %APPDATA%\Claude\claude_desktop_config.json
Add the following to your configuration...
{
"mcpServers": {
"actualBudget": {
"command": "npx",
"args": ["-y", "actual-mcp", "--enable-write"],
"env": {
"ACTUAL_DATA_DIR": "path/to/your/data",
"ACTUAL_PASSWORD": "your-password",
"ACTUAL_SERVER_URL": "http://your-actual-server.com",
"ACTUAL_BUDGET_SYNC_ID": "your-budget-id"
}
}
}
}
### a. Using Node.js (local only):
```json
{
"mcpServers": {
"actualBudget": {
"command": "node",
"args": ["/path/to/your/clone/build/index.js", "--enable-write"],
"env": {
"ACTUAL_DATA_DIR": "path/to/your/data",
"ACTUAL_PASSWORD": "your-password",
"ACTUAL_SERVER_URL": "http://your-actual-server.com",
"ACTUAL_BUDGET_SYNC_ID": "your-budget-id"
}
}
}
}
{
"mcpServers": {
"actualBudget": {
"command": "docker",
"args": [
"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"
]
}
}
}
After saving the configuration, restart Claude Desktop.
💡
ACTUAL_DATA_DIRis optional if you're usingACTUAL_SERVER_URL.
💡 Use
--enable-writeto enable write-access tools.
To expose the server over a port using Docker:
docker run -i --rm \
-p 3000:3000 \
-v "/path/to/your/data:/data" \
-e ACTUAL_PASSWORD="your-password" \
-e ACTUAL_SERVER_URL="http://your-actual-server.com" \
-e ACTUAL_BUDGET_SYNC_ID="your-budget-id" \
-e BEARER_TOKEN="your-bearer-token" \
sstefanov/actual-mcp:latest \
--sse --enable-write --enable-bearer
⚠️ Important: When using --enable-bearer, the BEARER_TOKEN environment variable must be set.
🔒 This is highly recommended if you're exposing your server via a public URL.
Once connected, you can ask Claude questions like:
Example Codex configuration:
In ~/.codex/config.toml:
[mcp_servers.actual-budget]
url = "http://localhost:3000"
Point Codex at the same port you pass to npm start -- --sse --port <PORT>.
For development with auto-rebuild:
npm run watch
To verify the server can connect to your Actual Budget data:
node build/index.js --test-resources
Since MCP servers communicate over stdio, debugging can be challenging. You can use the MCP Inspector:
npx @modelcontextprotocol/inspector node build/index.js
The end-to-end test suite (vitest.e2e.config.ts) spins up a real Actual Budget server in a Docker container (via Testcontainers), seeds a budget, and drives it through a real MCP client over stdio to verify accounts, transactions, categories, payees, rules, and imports actually persist. It requires Docker to be running locally.
In CI, the e2e-test job in .github/workflows/pr-validation.yml only runs on release-please PRs (branch prefix release-please--) or when a PR is given the run-e2e label — it does not run on every PR by default, since it needs Docker and takes longer than the standard checks.
To run it locally:
npm run build && npm run test:e2e
Docker must be installed and running; the test suite pulls and starts the Actual server image automatically.
index.ts - Main server implementationtypes.ts - Type definitions for API responses and parametersprompts.ts - Prompt templates for LLM interactionsutils.ts - Helper functions for date formatting and moreactual-mcp is published to the official MCP Registry
as io.github.s-stefanov/actual-mcp. Registry metadata lives in
server.json and is published automatically on each release
(see .github/workflows/release-please.yml).
It advertises two transports on the npm package — stdio (default) and
streamable-http (via the --sse flag). (A Docker image is also published,
but is not yet listed as a registry package.)
Post-release directory listings are tracked in
docs/mcp-registry-checklist.md.
MIT
Contributions are welcome! Please feel free to submit a Pull Request.
{ "mcpServers": { "actual-mcp": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}도구
아직 도구 목록이 없습니다. 원격 서버는 첫 상태 확인 후에 도구 목록이 생깁니다.
FAQ
이 페이지에서 Cursor, Claude Desktop, Claude Code 또는 VS Code용 stdio 설정을 복사합니다. PlugMCP 프록시가 아니라 게시자의 설치 방식을 사용합니다.
이 레코드에는 필수 환경 변수가 등록되어 있지 않습니다.
Actual은(는) stdio를 통해 로컬에서 실행됩니다.
마지막 확인: 2026-11-15. Actual Budget MCP server exposing API functionality