Ledgr

What the Ledgr MCP server does

The Ledgr MCP server gives MCP-compatible AI clients access to a self-hosted Ledgr finance installation. It connects the assistant to linked account balances, transactions, budgets, investment holdings, recurring bills, and financial reports. The server can also initiate an account sync, update transaction classifications, mark transfers, and change budget amounts when the client has the required write or sync permission.

Ledgr itself can collect data through Plaid or SimpleFIN, or through CSV, OFX, and QFX imports. Its finance application includes transaction categorization, budget tracking, investment views, bill detection, and reports for spending, income, cash flow, trends, and net worth. The MCP layer provides an agent-facing way to query and operate on that data.

How it works

The application runs on the user's own server, typically as a Docker Compose deployment with PostgreSQL. After MCP is enabled, clients connect to the instance at /api/mcp. The README documents http://localhost:4200/api/mcp for a local installation. An initial connection sends the user through OAuth authorization, where access is granted using separate read, write, and sync scopes: ledgr:read, ledgr:write, and ledgr:sync.

Read operations cover accounts, balances, transactions, categories, budgets, reports, holdings, portfolio summaries, upcoming bills, and the overall dashboard. Write operations include recategorizing transactions, changing transfer status, and setting category budgets. The sync operation triggers a bank synchronization. The client can also request an interactive financial dashboard widget.

Setup and configuration

Run Ledgr with Docker and Docker Compose, then enable the MCP endpoint in the environment file:

MCP_ENABLED=true

Restart the Compose deployment after changing the environment. Claude Code and Codex CLI have documented plugin installation commands, while other MCP clients can be pointed directly at the HTTP endpoint. Claude Desktop, Cursor, Windsurf, and Cline are listed as supported client types in the project documentation.

Plaid connections use PLAID_CLIENT_ID, PLAID_SECRET, and PLAID_ENV. SimpleFIN does not require application environment changes; users connect it from the Ledgr interface with a provider-issued Setup Token. Because SimpleFIN has no webhooks, its account updates run on a daily schedule controlled by SCHEDULER_SIMPLEFIN_SYNC_CRON.

On first startup, Ledgr creates an encryption key and session secret in its application data volume. Operators may set ENCRYPTION_KEY themselves. The data volume or the /data/encryption-key file should be backed up together with the database because losing the key prevents access to encrypted Plaid and SimpleFIN tokens.

Tools and capabilities

The Ledgr MCP server exposes these documented tools:

• List accounts and balances, or summarize totals by account type.
• Search and filter transactions.
• Change transaction categories and transfer status.
• Read monthly budget progress and set category budgets.
• List categories and produce spending or income-versus-expense reports.
• Review historical net worth, investment holdings, and portfolio allocation.
• Find upcoming recurring bills.
• Read a dashboard summary or display the financial dashboard widget.
• Trigger synchronization for connected accounts.

Limitations and notes

The Ledgr MCP server requires a running Ledgr deployment and authorization through its MCP OAuth flow. Available data depends on the accounts and imports configured in that installation. Plaid requires Plaid credentials, while SimpleFIN updates are scheduled rather than webhook-driven. The application can also operate without either provider by using supported file imports.

Tool permissions are scope-controlled, so a client cannot assume that write or synchronization actions are available after read access is granted. The project is licensed under AGPL-3.0 and stores financial data on the operator's server, subject to that deployment's backup and security practices.