Potencia tu agente
El comando propio del publicador. No es un endpoint de PlugMCP.
Host a copy with our keys and logs.
npx -y [email protected]Claude Code no tiene enlace de instalación para un comando local. Copia el comando de abajo y ejecútalo en una terminal.
claude mcp add actual-mcp-server -- npx -y actual-mcp-server@0.30.0Ejecútalo en una terminal.
{ "mcpServers": { "actual-mcp-server": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}claude_desktop_config.json
¿URL remota o un comando en tu máquina? En qué se diferencian las dos instalaciones
Ejecutar en 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.
AbrirTalk to your budget. Run it anywhere. Trust it in production.
Actual MCP Server is a Model Context Protocol server that connects any MCP-compatible AI assistant (such as LibreChat, LobeChat, Claude Desktop, and more) directly to your self-hosted Actual Budget instance. Ask natural language questions, create transactions, analyse spending, and manage your entire budget without ever opening the Actual Budget UI.
┌─────────────┐ MCP/HTTP ┌──────────────────┐ Actual API ┌──────────────┐
│ LibreChat │ ◄───────────► │ Actual MCP │ ◄───────────► │ Actual │
│ LobeChat │ │ Server │ │ Budget │
│ (remote) │ │ (84 tools) │ │ Server │
└─────────────┘ └──────────────────┘ └──────────────┘
┌─────────────┐ MCP/stdio ┌──────────────────┐ Actual API ┌──────────────┐
│ Claude │ ◄───────────► │ Actual MCP │ ◄───────────► │ Actual │
│ Desktop │ │ Server │ │ Budget │
│ (local) │ │ (84 tools) │ │ Server │
└─────────────┘ └──────────────────┘ └──────────────┘
Most Actual Budget MCP implementations are simple stdio bridges designed for single-user, local use with Claude Desktop. This project goes further:
--http), or as a direct local process for Claude Desktop (--stdio). No Docker or HTTP server is needed for local use.actual_budgets_switch. Works on both transports: HTTP keys the active budget to the MCP session, and stdio (Claude Desktop, Claude Code, Cursor) gets a synthetic per-process session so a switch is scoped to that process rather than shared globally (#348).Verified working with LibreChat, LobeChat, and Claude Desktop. All 84 tools tested end-to-end. Any MCP-compatible client should work.
docker run -d \
--name actual-mcp-server-backend \
-p 3600:3600 \
# Use the same URL you type in your browser to open Actual Budget:
# http://localhost:5006 (if Actual Budget runs on the same machine)
# http://192.168.1.50:5006 (if it runs on another machine on your network)
# https://actual.yourdomain.com (if you use a domain name)
# http://actual:5006 (if both containers share a Docker network; use container name)
-e ACTUAL_SERVER_URL=http://localhost:5006 \
-e ACTUAL_PASSWORD=your_password \
-e ACTUAL_BUDGET_SYNC_ID=your_sync_id \
-e MCP_SSE_AUTHORIZATION=your_secret_token \
-v actual-mcp-data:/app/data \ # required, see note below
-v actual-mcp-logs:/app/logs \
ghcr.io/agigante80/actual-mcp-server:latest
Why the
/app/datavolume is required: Actual Budget does not expose a REST API. The official@actual-app/apilibrary (used internally by this server) works by downloading a local copy of your budget data, running all queries on that local copy, then syncing changes back. The/app/datavolume gives the container a persistent, writable place to store that local copy (it is the directory the image creates and owns as the runtime user). Without it the container has nowhere to write and will fail on startup. See the Actual API docs for details.actual-mcp does not need to run on the same machine as Actual Budget. You can have Actual Budget on one server and actual-mcp on another - as long as
ACTUAL_SERVER_URLpoints to your Actual Budget instance, everything works.
Verify it's running:
# Quick health check
curl http://localhost:3600/health
# Expected: {"status":"ok","transport":"http","version":"..."}
# Full MCP handshake (also verifies your token)
curl -s -X POST http://localhost:3600/http \
-H "Authorization: Bearer your_secret_token" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"cli-test","version":"1.0"}}}' \
| python3 -m json.tool
# Success: JSON response with "protocolVersion" and "serverInfo"
# Wrong token: {"error": "Unauthorized"}
# Server not running: curl: (7) Failed to connect
Also available on Docker Hub: agigante80/actual-mcp-server:latest
git clone https://github.com/agigante80/actual-mcp-server.git
cd actual-mcp-server
cp .env.example .env # fill in ACTUAL_SERVER_URL, ACTUAL_PASSWORD, ACTUAL_BUDGET_SYNC_ID
docker compose --profile production up -d # production: MCP server listens on :3600
# or
docker compose --profile dev up -d # dev mode with hot-reload
The compose file defines only the
devandproductionprofiles. The MCP server listens on:3600directly: there is no bundled reverse proxy and no bundled Actual Budget server, so pointACTUAL_SERVER_URLat your own Actual instance. For TLS, enable native HTTPS withMCP_ENABLE_HTTPS=true(plusMCP_HTTPS_CERTandMCP_HTTPS_KEY), or front the server with your own reverse proxy.
Requires Node.js 22+. npm and npx do not enforce this, so check with
node --versionfirst. On an older Node the server refuses to start and tells you so. Note thatnpxruns whichevernodeis first on yourPATH, which is not always the one you installed most recently.
# Quick start via npx (no clone needed):
ACTUAL_SERVER_URL=http://localhost:5006 \
ACTUAL_PASSWORD=your_password \
ACTUAL_BUDGET_SYNC_ID=your-sync-id \
MCP_SSE_AUTHORIZATION=your_token \
npx actual-mcp-server --http
# Or clone for development / custom config:
git clone https://github.com/agigante80/actual-mcp-server.git
cd actual-mcp-server
npm install
cp .env.example .env # fill in required values
npm run build
npm run dev -- --http
Server starts at http://localhost:3600/http by default (the listen port is MCP_BRIDGE_PORT, default 3600).
The stdio transport runs the MCP server as a child process. Claude Desktop spawns it directly and communicates over stdin/stdout. No network port, no auth token, no Docker required. No cloning needed: npx downloads and caches the package automatically.
Add to claude_desktop_config.json (see docs/guides/MCP_CLIENTS_SETUP.md for config file location and all client options):
{
"mcpServers": {
"actual-budget": {
"command": "npx",
"args": ["-y", "actual-mcp-server", "--stdio"],
"env": {
"ACTUAL_SERVER_URL": "http://localhost:5006",
"ACTUAL_PASSWORD": "your_actual_password",
"ACTUAL_BUDGET_SYNC_ID": "your-sync-id-here",
"MCP_BRIDGE_DATA_DIR": "/absolute/path/to/data-dir"
}
}
}
}
No token needed. stdio runs as a local process owned by your user. The transport itself is the security boundary. All 84 tools are available.
MCP_BRIDGE_DATA_DIRshould be an absolute path. Without one, the data directory resolves relative to wherever the client spawns the process, which can be unpredictable. The directory is created automatically on first run.
Actual MCP Server is published in the Unraid Community Applications store: ca.unraid.net/apps/actual-mcp-server. This runs the HTTP transport, the right choice for LibreChat, LobeChat, and other remote MCP clients.
Install it from the Apps tab (Community Applications):
actual-mcp-server, then click Install.openssl rand -hex 32. A blank token disables all HTTP authentication and exposes your financial data unauthenticated on the LAN, so this is required (see Transport & Authentication).nobody:users) so the container can write the appdata Data and Logs directories, then start it.3600); point your MCP client at http://[server-ip]:3600/http with the Bearer token.The Unraid template lives in unraid/actual-mcp-server.xml. For the publishing workflow see docs/UNRAID_CA_PUBLISHING.md.
LibreChat / LobeChat: add to librechat.yaml (or LobeChat MCP plugin settings):
mcpServers:
actual-mcp:
type: "streamable-http"
url: "http://actual-mcp-server-backend:3600/http"
headers:
Authorization: "Bearer YOUR_TOKEN_HERE"
serverInstructions: true
timeout: 600000
See docs/guides/AI_CLIENT_SETUP.md for full LibreChat, LobeChat, network, and HTTPS/TLS proxy setup.
Claude Desktop via HTTP (when the server is already running as a Docker container):
{
"mcpServers": {
"actual-budget": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"http://localhost:3600/http",
"--header",
"Authorization: Bearer YOUR_TOKEN_HERE"
]
}
}
}
Claude Desktop via stdio (native, no HTTP server needed; see Option D above):
{
"mcpServers": {
"actual-budget": {
"command": "node",
"args": ["/absolute/path/to/actual-mcp-server/dist/src/index.js", "--stdio"],
"env": {
"ACTUAL_SERVER_URL": "http://localhost:5006",
"ACTUAL_PASSWORD": "your_password",
"ACTUAL_BUDGET_SYNC_ID": "your-sync-id",
"MCP_BRIDGE_DATA_DIR": "/absolute/path/to/actual-mcp-server/actual-data"
}
}
}
}
See docs/guides/MCP_CLIENTS_SETUP.md for all options (including Cursor, VS Code, Gemini CLI), Linux/NVM path fixes, and troubleshooting.
docker pull ghcr.io/agigante80/actual-mcp-server:latest
docker stop actual-mcp-server-backend
docker rm actual-mcp-server-backend
# Re-run the original docker run command with the same flags and volumes
Also available on Docker Hub: docker pull agigante80/actual-mcp-server:latest
docker compose pull
docker compose --profile production up -d
git pull
npm install
npm run build
# Then restart the server
If you run npx actual-mcp-server without a globally installed version, npx fetches the latest from the registry automatically. But if you previously installed it globally (npm install -g actual-mcp-server), the global install takes precedence, so you must upgrade it explicitly:
# Upgrade the global install
npm install -g actual-mcp-server
# Or force the registry version without touching your global install
npx actual-mcp-server@latest --http
For Claude Desktop (stdio), restart Claude after upgrading.
84 tools across all categories. All tools use the actual_<category>_<action> naming convention.
Standard (7)
Split transactions: pass a
subtransactionsarray (each child needs anamountin integer cents;categoryandnotesare optional). The child amounts must sum to the parentamount(the server does not enforce this, so the tool does). A split parent carries no category of its own: put categories on the children.actual_transactions_updatewithsubtransactionsedits the children of a transaction that is already a split, or splits a plain transaction IN PLACE: it keeps its id,imported_idand cleared state, so a bank-synced transaction can be split without breaking import matching. Its own category is cleared, and a child that names no category inherits it. A split child cannot itself be split. Note:actual_transactions_importforwards asubtransactionsarray to the API but does NOT apply the sum check, so useactual_transactions_createfor guaranteed-balanced splits.
Utility (2)
Exclusive ActualQL-powered (8), unique to this MCP server
Note: Use
actual_transfers_createfor any account-to-account movement, notactual_transactions_create. The dedicated tool creates both sides (debit and credit) atomically so the books stay balanced. Limitations: both accounts must exist and be open, andfrom_accountmust differ fromto_account.
actual_categories_get · actual_categories_create · actual_categories_update · actual_categories_delete
actual_category_groups_get · actual_category_groups_create · actual_category_groups_update · actual_category_groups_delete
actual_payees_get · actual_payees_common_list · actual_payees_create · actual_payees_update · actual_payees_delete · actual_payees_merge · actual_payee_rules_get
actual_tags_list · actual_tags_create · actual_tags_update · actual_tags_delete
actual_notes_get · actual_notes_update
actual_rules_get · actual_rules_create · actual_rules_update · actual_rules_delete
Four tools take many items in one call, for clients that allow only a few tool calls per turn. They share ONE contract: each item is applied independently and not atomically. There is no rollback, so items applied before a failure stay applied; a bad item is reported by its index and the rest continue; an infrastructure failure (lost connection, timeout) fails the whole call, and then you must read the data back before retrying anything. A bulk path never retries a create on its own.
actual_transactions_update_batch (counted under Transactions): update up to 50 transactions, {id, fields} each. Result: { succeeded: [{id}], failed: [{id, error}], total, successCount, failureCount }. Items marked "not attempted" were never sent. Re-read with actual_transactions_get before retrying any item.actual_transactions_import (counted under Transactions): bulk create with import semantics (deduplication and reconciliation against existing transactions, rules optionally applied). Use it to add many transactions at once.actual_budget_updates_batch: set budget amounts and/or carryover flags for 1 to 100 month/category pairs, and the way to rebalance categories: read the month with actual_budgets_getMonth, then send one batch of absolute amounts. Each operation needs at least one of amount (integer cents) or carryover. Result: { succeeded: [{index, month, categoryId}], failed: [{index, month, categoryId, error}], total, successCount, failureCount }. An unknown category, an out-of-range month or a carryover on an income category fails only that item. After a timeout, read the months back with actual_budgets_getMonth before retrying.actual_rules_create_batch (counted under Rules): create 1 to 50 rules, each exactly the input of actual_rules_create. Result: { succeeded: [{index, id}], failed: [{index, error}], total, successCount, failureCount }. Items marked "not attempted" were never sent. Re-read with actual_rules_get before retrying any item.actual_session_list · actual_session_close
All configuration is via environment variables. Copy .env.example to .env to get started.
All 84 tools are published by default. Chat clients with a small tool budget (Gemini, LibreChat) do better with fewer, so the surface can be narrowed at startup. A tool that is not published is also refused if a client calls it by name, and the refusal names the setting responsible.
Each tool is in exactly one group. The chat preset cuts across them and publishes 12 tools: actual_get_context, actual_query_run, actual_transactions_create, actual_transactions_update, actual_transactions_delete, actual_transactions_update_batch, actual_rules_create, actual_rules_create_batch, actual_budget_updates_batch, actual_budgets_transfer, actual_budgets_setAmount and actual_budgets_getMonth. Measured on the tools/list payload, all 84 tools are 108,164 bytes and the chat preset is 25,949 bytes (about 6.5k tokens saved, a 76% cut).
MCP_READ_ONLY=true additionally hides and refuses every write-capable tool (47 of the 83, including actual_bank_sync, actual_budgets_export, actual_budgets_switch and actual_session_close), leaving 36. actual_session_list stays available under read-only. See Security and Privacy.
Example: a chat assistant.
MCP_TOOLSETS=chat
MCP_TOOLS=actual_accounts_list,actual_payees_get
Example: a read-only household assistant.
MCP_TOOLSETS=context,analysis,query
MCP_READ_ONLY=true
A configuration that resolves to zero tools refuses to start.
Configure multiple Actual Budget files so the AI can switch between them at runtime using actual_budgets_list_available and actual_budgets_switch.
BUDGET_N_SERVER_URL and BUDGET_N_PASSWORD fall back to ACTUAL_SERVER_URL / ACTUAL_PASSWORD when omitted.
# Default budget
ACTUAL_SERVER_URL=http://actual:5006
ACTUAL_PASSWORD=my-password
ACTUAL_BUDGET_SYNC_ID=aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa
BUDGET_DEFAULT_NAME=Personal
# Budget 1 (same server, same password)
BUDGET_1_NAME=Family
BUDGET_1_SYNC_ID=bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb
# Budget 2 (different server)
BUDGET_2_NAME=Business
BUDGET_2_SERVER_URL=https://actual-office.example.com
BUDGET_2_PASSWORD=office-password
BUDGET_2_SYNC_ID=cccccccc-cccc-cccc-cccc-cccccccccccc
The server supports two transport modes:
The two modes are mutually exclusive. Pass exactly one flag when starting the server.
stdio is the simplest way to connect Claude Desktop directly to Actual Budget. The MCP server runs as a child process; Claude Desktop spawns it, communicates over stdin/stdout using NDJSON (the MCP wire format), and the process exits cleanly when Claude Desktop closes.
Key properties of stdio mode:
Start manually to verify:
cd /path/to/actual-mcp-server
ACTUAL_SERVER_URL=http://localhost:5006 \
ACTUAL_PASSWORD=your_password \
ACTUAL_BUDGET_SYNC_ID=your-sync-id \
node dist/src/index.js --stdio
Send a test request (keep stdin open with sleep):
{ echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'; sleep 5; } \
| ACTUAL_SERVER_URL=http://localhost:5006 ACTUAL_PASSWORD=your_password ACTUAL_BUDGET_SYNC_ID=your-sync-id \
node dist/src/index.js --stdio 2>/dev/null
Claude Desktop config (claude_desktop_config.json):
{
"mcpServers": {
"actual-budget": {
"command": "node",
"args": ["/absolute/path/to/actual-mcp-server/dist/src/index.js", "--stdio"],
"env": {
"ACTUAL_SERVER_URL": "http://localhost:5006",
"ACTUAL_PASSWORD": "your_actual_password",
"ACTUAL_BUDGET_SYNC_ID": "your-sync-id-here",
"MCP_BRIDGE_DATA_DIR": "/absolute/path/to/actual-mcp-server/actual-data"
}
}
}
}
Path must be absolute. Claude Desktop does not inherit shell
PATH, sonodemust also be absolute if you use NVM or a non-standard install:/home/youruser/.nvm/versions/node/v22.x.x/bin/node.
See docs/guides/MCP_CLIENTS_SETUP.md for all connection options (stdio native, mcp-remote via HTTP/HTTPS), other clients (Cursor, VS Code, Gemini CLI, Claude Code), Linux path fixes, and troubleshooting.
HTTP transport uses the /http endpoint (StreamableHTTP) with optional Bearer token or OIDC authentication.
# Generate a token
openssl rand -hex 32
# Add to .env
MCP_SSE_AUTHORIZATION=your_token_here
Clients send: Authorization: Bearer your_token_here
AUTH_PROVIDER=oidc
OIDC_ISSUER=https://sso.yourdomain.com
OIDC_RESOURCE=https://actual-mcp.yourdomain.com/http # this server's public MCP URL (the expected 'aud')
OIDC_ACCEPTED_AUDIENCES=your-client-id # only if your IdP puts the client id in 'aud' (#245)
OIDC_SCOPES= # leave empty when the tokens carry no scope claim
# OIDC_SCOPES_SUPPORTED=openid,offline_access # extra scopes advertised in discovery without enforcement (#472)
OIDC_RESOURCE is the canonical URL of this MCP server (the MCP authorization spec's "canonical server URI" and the RFC 9728 resource identifier), not an IdP client id: the protected-resource metadata route and the expected token audience are both derived from it, and a value that is not an absolute http(s) URL refuses to start with a message naming the variable (#461). Use the full public endpoint URL (https://host/http, or whatever MCP_BRIDGE_HTTP_PATH / MCP_HTTP_PATH advertises) rather than the bare origin: with the endpoint form the server publishes both the path-specific document (canonical) and a root copy for clients that look only at the root (#473), and it warns at startup when the resource path and advertised path disagree.
OAuth discovery endpoints (automatic in OIDC mode). When AUTH_PROVIDER=oidc, the server publishes the two metadata documents an OAuth client needs to bootstrap a login, so mcp-remote and Claude.ai's native connector can discover the flow without manual endpoint configuration:
GET /.well-known/oauth-protected-resource[<path>] (RFC 9728): identifies this server as a protected resource and points at your OIDC_ISSUER as the authorization server. The route follows OIDC_RESOURCE: with https://host/http, the canonical document is served at /.well-known/oauth-protected-resource/http (RFC 9728 section 3.1) and a root copy is also served at /.well-known/oauth-protected-resource for clients that skip the path-specific URL (e.g. Google Gemini, #473); the bare origin serves only the root path. The official MCP SDK tries the path-specific URL first and falls back to the root.GET /.well-known/oauth-authorization-server (RFC 8414, #285): the authorization server metadata (its authorization_endpoint / token_endpoint / registration_endpoint), re-served from your IdP's own OpenID discovery document. This is here because several clients look for it on the resource-server origin, and some IdPs (e.g. Authentik) do not expose it where those clients look. It is fetched once at startup and served verbatim, exposes only endpoints your IdP already publishes publicly, and requires no authentication (a client reads it before it has a token). No extra configuration is needed; it is absent when AUTH_PROVIDER is not oidc.Where the per-user budget ACL comes from. By default the ACL is the AUTH_BUDGET_ACL map you maintain by hand. Since v0.10.x it can instead be derived from the Actual server's own per-file access list, so granting or revoking someone in Actual takes effect here without a config edit and a restart:
AUTH_BUDGET_ACL_SOURCE=actual # default: static (the AUTH_BUDGET_ACL map)
AUTH_BUDGET_ACL_CLAIM=auto # default: mirrors Actual's own claim precedence
How the match works. Actual does not store your IdP's sub. When a user logs in, Actual resolves their identity as the first non-empty of preferred_username, login, email, id, sub, saves that string as the user's userName, and generates its own unrelated UUID as userId. The ACL therefore matches your token against userName, using that same precedence. AUTH_BUDGET_ACL_CLAIM=auto (the default) does exactly this; set it to a single claim name to pin one instead.
Three things to know before enabling it:
ACTUAL_OPENID_*. On a password-only server no named users exist and every principal resolves to nothing.@actual-app/api authenticates with a password, and an Actual server set up with OpenID from scratch refuses password login, so this server cannot connect to it at all. A password cannot be added afterwards.sub is unique and never reassigned; preferred_username and email carry no such guarantee and are often editable by the user. This exposure is inherited from Actual, which keys its own accounts the same way, not introduced here: anyone who can set their preferred_username to yours can impersonate you in Actual's login too. If that matters to you, pin AUTH_BUDGET_ACL_CLAIM to a claim your IdP does not let users edit, and make sure that is the claim your IdP uses to populate Actual's user_name.It is opt-in and fails closed: if the budget list cannot be read, or the principal matches no file, access is denied rather than granted.
See AI Client Setup, OIDC for AUTH_BUDGET_ACL format, Casdoor notes, and the Cloudflare Access for SaaS + Gemini recipe.
Integration test levels (tests/manual/): sanity → smoke → normal → extended → full → cleanup
See tests/manual/README.md and tests/e2e/README.md for details.
Contributions are welcome! See CONTRIBUTING.md for development setup, code standards, and the PR process.
Quick flow:
git checkout -b feature/my-featurenpm run build && npm run test:unit-js must pass@modelcontextprotocol/sdk@actual-app/api--http) · StdioServerTransport (--stdio)Every Actual API call goes through the withActualApi() wrapper in src/lib/actual-adapter.ts, which handles init/shutdown lifecycle, retry (3 attempts, exponential backoff), and concurrency limiting. See docs/ARCHITECTURE.md for full design documentation.
MIT. See LICENSE for details.
This project started as a personal learning exercise to explore the Model Context Protocol technology. It is an independent open-source project, not affiliated with, endorsed by, or supported by Actual Budget or any other organisation.
The software is provided as-is, without warranty of any kind. The author accepts no responsibility for how it is used, for any data loss, financial errors, or other consequences arising from its use. If you connect it to real financial data, you do so entirely at your own risk.
Version: 0.24.3 | Tool Count: 84 (verified LibreChat-compatible)
I build and maintain this in my own time. It is free, it stays free, and it gets maintained either way.
If it saved you some time and you feel like saying thanks, you can do that at github.com/sponsors/agigante80. Entirely optional, and nothing about the project changes either way.
MCP server with 85 tools for AI-driven financial management with Actual Budget. HTTP and stdio transports for LibreChat, Claude Desktop, Cursor, VS Code, Gemini CLI
{ "mcpServers": { "actual-mcp-server": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}Herramientas
Aún no hay lista de herramientas. Los servidores remotos la reciben tras la primera comprobación de estado.
Preguntas frecuentes
Copia en esta página la configuración stdio para Cursor, Claude Desktop, Claude Code o VS Code. Usa la instalación del publicador, no un proxy de PlugMCP.
Este registro no indica ninguna variable de entorno obligatoria.
Actual se ejecuta localmente por stdio.
Última comprobación: 2026-11-14. MCP server with 85 tools for AI-driven financial management with Actual Budget. HTTP and stdio transports for LibreChat, Claude Desktop, Cursor, VS Code, Gemini CLI