Ledgr

io.github.KenTaniguchi-Rv0.3.4Updated Oct 9, 2026

Self-hosted personal finance app with bank sync, budgets, net worth and investment tracking

VerifiedSTDIODesktop onlyFinanceData & AnalyticsProductivity & Workflow

Overview

AI-generated overview

Lets an assistant query and update a self-hosted Ledgr personal finance instance: accounts, transactions, budgets, reports, and investments.

What it does
Ledgr is a self-hosted personal finance app that syncs bank accounts through Plaid or SimpleFIN and exposes an MCP endpoint. Tools include list_accounts, get_account_summary, get_transactions, get_budget, set_budget_category, get_spending_report, get_income_vs_expense, get_net_worth_history, get_holdings, get_portfolio_summary, get_upcoming_bills, get_dashboard_summary, show_financial_dashboard, update_transaction_category, mark_transaction_transfer, and sync_accounts. Read, write, and sync tools are gated by OAuth scopes ledgr:read, ledgr:write, and ledgr:sync granted during authorization.
When to use it
Use it when you already run Ledgr and want to ask about spending, budgets, bills, net worth, or holdings in natural language, or to recategorize transactions and trigger a sync from an assistant instead of the web dashboard.
Requirements
A running Ledgr instance with its own PostgreSQL database, reachable at the configured LEDGR_URL; MCP_ENABLED must be set to true. The MCP endpoint is served at /api/mcp and uses an OAuth flow on first connection. Docker is used for the packaged deployment; DATABASE_URL is required and BETTER_AUTH_URL must match LEDGR_URL.
Before you install
The server can change data: update_transaction_category, mark_transaction_transfer, set_budget_category, and sync_accounts write to your financial records, so grant only the OAuth scopes you need. It handles sensitive financial data and bank-link tokens; losing the encryption key stored in the app data volume means losing access to encrypted Plaid and SimpleFIN tokens, so back up that volume with the database. Optional Plaid and AI provider keys are configured by environment variable.

Installation

In SourceWeft

  1. Open Ledgr in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

[Ledgr]

Ledgr

Self-hostable personal finance app with automatic bank sync and AI agent support.

[License: AGPL v3] [TypeScript] [Next.js] [Docker] [MCP]

[Ledgr Dashboard]

Ledgr connects to your bank accounts through Plaid or SimpleFIN, automatically syncs and categorizes transactions, and gives you budgets, investment tracking, bill detection, and financial reports — all running on your own server with your own data.

It also exposes an MCP server, so AI assistants like Claude can query your finances through natural conversation.

You: "How much did I spend on dining out last month?"Claude: Based on your transactions, you spent $342.18 on dining out in April...
[Ledgr MCP demo in Claude Code]
Querying your finances from Claude Code via MCP

Features

  • Automatic bank sync — connect 12,000+ banks via Plaid (real-time webhook sync or scheduled polling), or via SimpleFIN if you'd rather not use a Plaid developer account
  • Smart categorization — four-tier pipeline: your rules > merchant defaults > Plaid categories > AI fallback
  • Budgets — set monthly budgets by category, track progress in real time
  • Investment tracking — portfolio holdings, performance history, and allocation breakdowns, synced automatically from Plaid or SimpleFIN
  • Recurring bill detection — automatically identifies subscriptions and recurring charges
  • Financial reports — spending, income, net worth, and category trends over time
  • AI agent interface (MCP) — query your finances from Claude Code, Claude Desktop, Cursor, or any MCP client
  • In-app AI chat — ask questions about your finances right from the dashboard
  • BYOK AI — bring your own API key (OpenAI, Anthropic, Google, or local models) for chat and categorization
  • CSV/OFX/QFX import & CSV export — for accounts not supported by Plaid, and for getting your data out
  • Self-hosted — Docker Compose with PostgreSQL, your data never leaves your server
[Ledgr budgets screen with per-category spending progress]
Monthly budgets by category, tracked against real spending

[Ledgr spending report with category breakdown]
Spending, income, cash flow, trends, and net worth reports

Quick Start

Requires Docker and Docker Compose.

bash
curl -fsSL https://raw.githubusercontent.com/KenTaniguchi-R/ledgr/main/scripts/install.sh | sh

This creates a ledgr/ directory, downloads docker-compose.yml, and starts the app.

Prefer to see the steps first?
bash
mkdir ledgr && cd ledgrcurl -O https://raw.githubusercontent.com/KenTaniguchi-R/ledgr/main/docker-compose.ymldocker compose up -d

Visit http://localhost:4200, create an account, and start exploring.

On first boot, Ledgr generates an encryption key and session secret and stores them in the app data volume. Back up that volume (or the /data/encryption-key file) along with your database — losing the key means losing access to encrypted data like Plaid and SimpleFIN tokens. Prefer to manage the key yourself? Set ENCRYPTION_KEY in a .env file (see Configuration) and it takes precedence.

Add your Plaid keys to .env to enable bank sync — see Connect Your Bank below (or skip the keys and use SimpleFIN). The app works without either via CSV import.

Connect Your Bank

  1. Sign up at dashboard.plaid.com and get your client_id and secret from Developers > Keys
  2. Add them to a .env file next to your docker-compose.yml (start from .env.example if you don't have one):
    env
    PLAID_CLIENT_ID=your_client_idPLAID_SECRET=your_secretPLAID_ENV=production      # or sandbox for fake data
  3. Restart: docker compose restart
  4. In the app, go to Accounts > Link Bank to connect via Plaid

Plaid's free trial plan includes 10 production connections and unlimited sandbox access. After that, the Launch plan is pay-as-you-go with no contract. Don't have Plaid keys yet? The app still works — import transactions via CSV and add Plaid later.

[Plaid Link bank connection]
Connect any of 12,000+ banks through Plaid

Or connect via SimpleFIN

SimpleFIN works out of the box — no developer account or .env changes needed.

  1. Get a SimpleFIN Bridge account and generate a Setup Token from your bridge provider
  2. In the app, go to Accounts > Link Bank and choose the SimpleFIN option
  3. Paste your Setup Token to connect

SimpleFIN has no webhooks, so accounts sync on a daily schedule (SCHEDULER_SIMPLEFIN_SYNC_CRON, see Configuration) instead of in real time. Investment holdings sync the same way as they do for Plaid.

Connect Your AI Agent

Ledgr ships with a built-in MCP server and plugin support.

First, enable the MCP endpoint in your .env and restart:

env
MCP_ENABLED=true

Then pick your tool:

Claude Code

bash
/plugin marketplace add KenTaniguchi-R/ledgr/plugin install ledgr@ledgr

Codex CLI

bash
codex plugin marketplace add KenTaniguchi-R/ledgr

OpenCode — add to opencode.json:

json
{  "$schema": "https://opencode.ai/config.json",  "plugin": ["ledgr"]}

OpenClaw

bash
openclaw plugins install ledgr --marketplace KenTaniguchi-R/ledgr

Hermes

bash
hermes plugins install KenTaniguchi-R/ledgr
Other MCP clients (Cursor, Windsurf, Cline, etc.)

Point any MCP-compatible client to your Ledgr instance:

http://localhost:4200/api/mcp

On first connection, Ledgr redirects you through an OAuth flow to authorize access.

Available Tools

ToolDescription
list_accountsLinked bank accounts and balances
get_account_summaryBalance totals by account type
get_transactionsSearch and filter transactions
update_transaction_categoryRecategorize a transaction
mark_transaction_transferMark or unmark a transaction as a transfer
get_budgetBudget progress for a month
set_budget_categorySet a category's budget amount
list_categoriesSpending categories
get_spending_reportSpending breakdown over a date range
get_income_vs_expenseIncome vs. expense trends
get_net_worth_historyNet worth over time
get_holdingsInvestment portfolio holdings
get_portfolio_summaryPortfolio value and allocation
get_upcoming_billsRecurring transactions and bills
get_dashboard_summaryOverview of your finances
show_financial_dashboardInteractive dashboard widget
sync_accountsTrigger a bank sync

Read, write, and sync tools are gated by OAuth scopes (ledgr:read, ledgr:write, ledgr:sync) that you grant during authorization.

Example prompts:

  • "How much did I spend on groceries this month?"
  • "Show me my budget status"
  • "What recurring bills do I have?"
  • "Generate a spending report for Q1"
  • "Sync my accounts and show my balances"

Comparison

LedgrActual BudgetFirefly III
Automatic bank syncPlaid (12,000+ banks) or SimpleFINSimpleFIN (US/CA), GoCardless (EU/UK)SimpleFIN, GoCardless, Spectre (via Data Importer)
Built-in MCP serverYes----
AI categorizationYes (BYOK)----
Investment trackingYes----
Self-hostableYesYesYes
DatabasePostgreSQLSQLiteMySQL/Postgres
LicenseAGPL-3.0MITAGPL-3.0

Updating

bash
docker compose pulldocker compose up -d

Migrations run automatically on container startup.

Configuration

VariableRequiredDefaultDescription
ENCRYPTION_KEYNoauto-generatedEncrypts Plaid tokens & API keys. Generated on first boot and persisted in the app data volume; set your own with openssl rand -hex 32
BETTER_AUTH_SECRETNoauto-generatedSession secret, persisted in the app data volume. Set your own with openssl rand -base64 32
PORTNo4200Host port for the app
POSTGRES_PASSWORDNoledgrDatabase password (change in production)
PLAID_CLIENT_IDNo--Plaid client ID
PLAID_SECRETNo--Plaid secret key
PLAID_ENVNoproductionproduction or sandbox
PLAID_SYNC_MODENopollpoll (scheduled) or webhook (real-time)
PLAID_WEBHOOK_URLNo--Public URL for Plaid webhooks (webhook mode)
SCHEDULER_SIMPLEFIN_SYNC_CRONNo45 4 * * *Daily SimpleFIN account sync (no webhooks, so this is the only sync trigger)
AI_PROVIDERNo--openai, anthropic, google, or custom
AI_API_KEYNo--Provider API key for AI chat & categorization
MCP_ENABLEDNofalseEnable the MCP endpoint for AI agents

See .env.example for all options.

Development

If you're self-hosting Ledgr, use the Quick Start above. The instructions below are for contributors.

Prerequisites

  • Node.js 24+
  • pnpm 10+
  • PostgreSQL 18 (or pnpm dev:db to start one in Docker)

Setup

bash
git clone https://github.com/KenTaniguchi-R/ledgr.gitcd ledgrpnpm installcp .env.example .env        # Fill in ENCRYPTION_KEYpnpm dev:setup              # Start DB + migrate + dev server

To run the full app in Docker from source (instead of pulling the pre-built image):

bash
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d

Commands

bash
pnpm dev                    # Dev server (Turbopack)pnpm test                   # Unit + integration testspnpm test:e2e               # Playwright E2E testspnpm lint                   # ESLintpnpm typecheck              # Type checkingpnpm db:studio              # Drizzle Studio (DB browser)

Tech Stack

LayerChoice
FrameworkNext.js 16 (App Router)
LanguageTypeScript
UIshadcn/ui + Tailwind CSS 4
ChartsRecharts 3
DatabasePostgreSQL 18 via Drizzle ORM
AuthBetter Auth
Bank SyncPlaid Node SDK, SimpleFIN
AIVercel AI SDK (BYOK)
MCPModel Context Protocol SDK
TestingVitest + Playwright + Stryker

Roadmap

  • Plaid webhook support (real-time sync)
  • AI chat assistant (in-app)
  • OFX/QFX import
  • SimpleFIN bank sync (Plaid alternative)
  • Automatic transfer detection between accounts
  • Mobile-responsive UI
  • Multi-currency support
  • Custom report builder
  • Goal tracking (savings goals, debt payoff)
  • Recurring budget templates

See Issues for what's being worked on.

Security

Security is critical for a finance app. If you discover a vulnerability, please do not open a public issue. Instead, see SECURITY.md for responsible disclosure instructions.

For details on how Ledgr handles your data, see PRIVACY.md.

Contributing

Contributions are welcome! Please open an issue first to discuss what you'd like to change. See CONTRIBUTING.md for setup and workflow details.

  1. Fork the repo
  2. Create your branch (git checkout -b feat/my-feature)
  3. Commit your changes
  4. Push and open a Pull Request

License

AGPL-3.0 — you can self-host freely. If you modify and distribute the server, you must open-source your changes.

Source: README.md at commit 0affc66

Tools

0
Tool metadata has not been indexed yet.

Version history

1
  1. v0.3.4LatestOct 9, 2026