actual

This MCP server acts as a bridge between AI assistants (like LibreChat or LobeChat) and the Actual Budget API. It exposes 62 specialized MCP tools that cover the majority of Actual Budget operations, including transactions, budgets, accounts, payees, and automation rules. The server is designed to be used within a conversational AI workflow, translating natural language requests into precise Actual Budget API calls and returning structured results suitable for chat responses. When integrated with an MCP client, you can ask questions like “What were my grocery expenses last month?” or instruct the model to perform bulk operations such as transferring budget amounts or creating automation rules, all through conversational prompts.

To use it, deploy the MCP server in your chosen environment (Docker, Node.js runtime, or other supported methods per your setup). Then configure your MCP client (e.g., LibreChat or LobeChat) to point at the server’s HTTP endpoint (for example, http://<host>:3000/http). The server will authenticate using the Bearer token or your configured authentication method and translate your requests into Actual Budget API calls, returning consolidated results suitable for chat-style presentation.

Prerequisites:

• Node.js >= 20.x installed on your machine or server
• npm (usually comes with Node.js)
• Access to the Actual Budget API (credentials or OAuth setup as required)

1. Install dependencies and build

   • Clone the repository
   • Install dependencies npm install
   • Build the TypeScript sources (if applicable) npm run build

2. Configure environment

   • Copy .env.example to .env and fill in your values, or configure via your deployment environment variables
   • Required variables (example): PORT=3000 AUTH_TOKEN=your-token ACTUAL_API_BASE_URL=https://api.actualbudget.com

3. Run the server

   • Local development: npm run start
   • Or run directly with Node (if built to dist): node dist/server.js

4. Verify deployment

   • Send a test request to http://localhost:3000/http or the configured endpoint to ensure the MCP server responds.

Tips and common considerations:

• Ensure the server has network access to the Actual Budget API and that any required OAuth credentials or API keys are properly configured.
• If using Docker, ensure the container is on the same virtual network as your MCP clients and that port mappings match your client configuration.
• Enable appropriate logging (LOG_LEVEL) to facilitate debugging during setup and initial usage.
• The MCP tools rely on 84% API coverage and 62 tools; if a specific tool isn’t responding as expected, check the Actual Budget API status and tool availability.
• For security, prefer Bearer token authentication or a secure OAuth flow over basic auth, especially in production deployments.