Power your agent
คำสั่งของผู้เผยแพร่เอง ไม่ใช่เอนด์พอยต์ของ 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
คัดลอกคอนฟิก stdio สำหรับ Cursor, Claude Desktop, Claude Code หรือ VS Code ได้ในหน้านี้ คอนฟิกนี้ใช้การติดตั้งของผู้เผยแพร่ ไม่ใช่พร็อกซีของ PlugMCP
ระเบียนนี้ไม่ได้ระบุตัวแปรสภาพแวดล้อมที่จำเป็น
Actual ทำงานแบบโลคัลผ่าน stdio
ตรวจสอบล่าสุดเมื่อ 2026-11-13 Actual Budget MCP server exposing API functionality