Skip to main content
Glama
tuskledger-mcp

tuskledger-mcp

tuskledger-mcp

Model Context Protocol server for Tusk Ledger. Gives your AI assistant typed access to your local personal finance data β€” without sending anything outside your machine.

🌐 Project site: www.tuskledger.com β€” what the parent app does, feature tour, public demo, and architecture. This package is the MCP bridge.

CI License: MIT Python 3.10+ Local-first Tools: 23 Main app


Quick context

Tusk Ledger is a self-hosted, Mint-style personal finance app that pulls your accounts via Plaid and runs entirely on your laptop. This package (tuskledger-mcp) is the bridge that lets an AI assistant β€” Claude Desktop, Cursor, Cowork, Claude Code, anything that speaks MCP β€” read that data and answer questions about your finances using typed tool calls instead of scraping the React UI.

Related MCP server: OpenBudget MCP Server

What you can ask your assistant

Once the server is wired up, these all work in plain English:

  • "Categorize the last 6 months of transactions from Whole Foods as Groceries instead of Shopping." β†’ Assistant queries them, you confirm, then makes a rule.

  • "What did I spend on coffee last quarter?" β†’ 3 seconds, no UI clicks.

  • "My net worth dropped this morning β€” what's causing it?" β†’ Assistant pulls accounts, balances, and recent transactions and diagnoses.

  • "Am I on track to max out my HSA this year?" β†’ Reads HSA bucket + YTD contributions + IRS limit, returns the gap.

  • "What subscriptions am I paying for that I haven't used recently?" β†’ Lists recurring charges with cadence and last-paid date.

  • "Will my checking dip below $1k before payday?" β†’ Pulls upcoming bills + paychecks and projects a running balance.

Local-first, no exceptions. The server talks only to your Tusk Ledger backend on http://127.0.0.1:8000. There is no "MCP cloud" β€” this is one Python process on your machine, talking to another Python process on the same machine. Your transactions never leave the laptop.

What tools are available

23 read-mostly tools. Group at a glance:

Group

Tools

Accounts

list_accounts, list_stale_accounts

Transactions

query_transactions, search_transactions

Spending insight

get_spending_summary, get_top_merchants, get_recurring_subscriptions, get_merchant_details

Cash flow

get_upcoming_bills, get_cash_flow_forecast

Budgets

get_budget (limits; pair with get_spending_summary for over/under)

Net worth & investments

get_net_worth, get_holdings, get_investments_summary

Taxes & planning

get_trading_tax_summary (FIFO + wash sales), get_retirement_projection (Monte Carlo)

Ops

run_sync (trigger a Plaid pull)

Full schemas (parameters, defaults, examples) are reported by the server itself β€” your MCP client renders them, and they're also visible in tuskledger_mcp/server.py.

Prerequisites

  • A running Tusk Ledger install (the main app), reachable on http://127.0.0.1:8000

  • The backend started with DEV_BYPASS_AUTH=true β€” v0 of the MCP server is auth-bypass-only. If you leave auth on you'll get 401 on every tool call. See Auth below for the rationale and the auth-aware roadmap.

  • Python 3.10+

  • An MCP-aware client (Claude Desktop, Cursor, Cowork, Claude Code, …)

Install

A note for users coming from MCP marketplace listings (LobeHub, Glama, mcp.so, etc.): these directories try to auto-install MCP servers in a sandbox to verify they boot. This server intentionally won't pass that check, because it requires the main Tusk Ledger app already running on your machine. The "cannot be installed" / red badges on those listings are about the auto-installer, not about this package. Use one of the manual config snippets below.

Option A β€” uvx (recommended; no permanent install)

If you have uv (pip install uv):

// In your MCP client's config
{
  "mcpServers": {
    "tuskledger": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/BradMorphsters/tuskledger-mcp", "tuskledger-mcp"]
    }
  }
}

uvx handles the isolated Python env; nothing pollutes your global Python. The server is fetched and cached on first invocation.

Option B β€” pip install from GitHub

pip install git+https://github.com/BradMorphsters/tuskledger-mcp

Then point your MCP client at the installed tuskledger-mcp binary:

{
  "mcpServers": {
    "tuskledger": {
      "command": "tuskledger-mcp"
    }
  }
}

(Use the full path from which tuskledger-mcp if you're using a venv.)

Option C β€” clone for development

git clone https://github.com/BradMorphsters/tuskledger-mcp
cd tuskledger-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e .

Where MCP client configs live

Client

Config path

Claude Desktop (macOS)

~/Library/Application Support/Claude/claude_desktop_config.json

Claude Desktop (Windows)

%APPDATA%\Claude\claude_desktop_config.json

Cursor

Settings β†’ Features β†’ Model Context Protocol β†’ paste the same mcpServers JSON shown above

Cowork

Same mcpServers JSON as Claude Desktop. Add it via Cowork's MCP server settings (or, if you're managing it as a plugin, ship the snippet inside the plugin's .mcp.json). Anthropic MCP docs

Claude Code

Project-level .claude/mcp.json, or user-level via claude mcp add tuskledger uvx --from git+https://github.com/BradMorphsters/tuskledger-mcp tuskledger-mcp

After editing the config, restart the client. The server boots when the client starts and shuts down when it closes.

Configuration

Two environment variables, both optional:

Var

Default

Notes

TUSKLEDGER_BASE_URL

http://127.0.0.1:8000

Where your Tusk Ledger backend listens. Override if you've moved the port.

TUSKLEDGER_TIMEOUT_SECONDS

10

Per-request timeout. Bump if your DB is huge and a query takes a while.

Example:

{
  "mcpServers": {
    "tuskledger": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/BradMorphsters/tuskledger-mcp", "tuskledger-mcp"],
      "env": {
        "TUSKLEDGER_BASE_URL": "http://127.0.0.1:8000",
        "TUSKLEDGER_TIMEOUT_SECONDS": "30"
      }
    }
  }
}

Auth

This v0 assumes your Tusk Ledger backend is running with DEV_BYPASS_AUTH=true (the common single-machine pattern documented in the main repo's README). If you've kept auth enabled, the MCP server's calls will fail with 401s and you'll see the error in your assistant's response.

Auth-aware support is on the roadmap. Until then, if you want both auth and MCP, run the backend with DEV_BYPASS_AUTH=true only when you're using the assistant, and flip it back when you're done.

What this server intentionally does NOT do

By design, v0 is read-mostly. The server doesn't expose:

  • Deleting accounts, transactions, rules, or goals

  • Modifying the database schema or running migrations

  • Disabling auth or rotating the encryption key

  • Touching Plaid access tokens

  • Sending data anywhere outside 127.0.0.1

The reasoning: an AI assistant should be able to help you understand your data and run safe operations (sync, queries), but irreversible changes belong in the web UI where you can see what's about to happen. We may add structured write tools (e.g. "create a rule") in later versions with explicit confirmation flows, but the bar will stay high.

Troubleshooting

Could not reach Tusk Ledger backend at http://127.0.0.1:8000 β€” Your Tusk Ledger app isn't running. From the main repo: ./start.sh.

401 Unauthorized from any tool β€” Auth is on. See the Auth section above. Run with DEV_BYPASS_AUTH=true for now.

404 Not Found β€” The backend doesn't have the endpoint we're trying to hit. Probably means you're on an older version of Tusk Ledger. Update the main app, restart your MCP client.

Tools don't appear in your assistant β€” The MCP server failed to boot. Check your client's MCP server logs (Claude Desktop has a "View MCP server logs" menu item). Common causes: bad path in the config, Python not on PATH, uvx not installed.

General health check β€” From the main Tusk Ledger repo: ./tuskledger doctor. This is the canonical diagnostic for the whole install.

Development

git clone https://github.com/BradMorphsters/tuskledger-mcp
cd tuskledger-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e .
pip install pytest pytest-asyncio
pytest tests/ -v

The tests don't bring up an MCP transport β€” they exercise the dispatch layer directly with a mock client. The MCP protocol itself is just a wrapper.

CI runs the same suite on Python 3.10/3.11/3.12 via GitHub Actions (see .github/workflows/ci.yml).

Available Tools

13 tools
get_holdingsA

Current investment holdings across every connected brokerage and 401(k). Returns symbol, account, quantity, current value, and unrealized gain/loss per position.

Inputs: no named parameters.

get_investments_summaryA

Roll-up of investment portfolio: total value, asset allocation (stocks/bonds/cash), top 5 holdings, % YTD gain. The 'how are my investments doing?' answer.

Inputs: no named parameters.

get_net_worthA

Current net worth (assets minus liabilities) plus a 12-month trend. Numbers are point-in-time from the last sync, not live-computed. Use list_stale_accounts to verify freshness.

Inputs: history.

get_recurring_subscriptionsA

List detected recurring subscriptions: Netflix, Spotify, gym, etc. Returns merchant, cadence (monthly/annual/etc.), last amount, next expected date, and confidence. The user often asks 'what subscriptions do I have' β€” this answers it.

Inputs: no named parameters.

get_retirement_projectionA

Run the multi-decade Monte Carlo retirement simulator. Returns probability of success, depletion age, and summary at key milestones (retirement, age 73 for RMDs, etc.).

Caveat: scenarios live in the Tusk Ledger UI's localStorage on the device the user last edited from β€” they aren't accessible to this tool. So the user (or their assistant) must supply at least current_age. Other params accept sensible defaults that match the standard 4% rule scenario; pass any you know to tighten the projection. To pull a saved scenario verbatim, the user can copy it out of the Retirement page in the UI and paste the values into the assistant's prompt.

Inputs: current_age (required), retirement_age, spouse_age, spouse_retirement_age, +8 more.

get_spending_summaryB

Aggregated spending totals broken down by category for a date range. Returns totals + per-category subtotals + counts. Defaults to the current calendar month if no dates given.

Inputs: start_date, end_date, exclude_business.

get_top_merchantsA

Top N merchants by total spend in a date range. Returns merchant name, total amount, transaction count, and a sparkline of the monthly trend. Useful for 'who am I paying the most?'.

Inputs: start_date, end_date, limit.

get_upcoming_billsA

Forward 30-day calendar of expected bills + paychecks with a running balance. Returns each event's date, amount, source (merchant or paycheck), and the projected account balance after that event. Useful for 'is my account going to dip before payday?'.

Inputs: days.

list_accountsA

List every connected account in Tusk Ledger with current balance, type (checking, savings, credit, investment, loan), and last-sync timestamp. Use this first to understand what accounts exist before drilling into transactions or holdings.

Inputs: no named parameters.

list_stale_accountsA

Return accounts whose data is older than the freshness threshold (a week for synced accounts, a month for manual). Useful when the user asks 'why is my net worth wrong?' β€” stale balances are usually the cause.

Inputs: no named parameters.

query_transactionsA

List transactions matching optional filters. Returns the most recent matches first. Common filter combos: β€’ account_id + start_date + end_date β†’ 'all transactions in my checking account this month' β€’ category='Coffee' + start_date='2026-01-01' β†’ 'every coffee purchase since New Year' Defaults to no filter (returns the most recent 100 transactions across all accounts).

Inputs: account_id, category, start_date, end_date, +1 more.

run_syncA

Trigger a Plaid sync across all connected items. Same as clicking 'Sync Now' in the UI. Returns a summary of what was fetched (accounts updated, transactions added). Safe to call freely β€” Plaid dedupes.

Inputs: no named parameters.

search_transactionsA

Free-text search across transaction names, merchant names, and notes. Use when the user asks 'find that Whole Foods charge from last week' or 'when did I last pay Verizon?'. Different from query_transactions in that this is a fuzzy text search, not a structured filter.

Inputs: q (required), limit.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 13 tools

    Disambiguation5/5

    Each tool targets a distinct financial domain: holdings vs investment summary vs net worth, and query vs search transactions are clearly differentiated. Descriptions provide clear purpose for each tool.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern (e.g., get_holdings, list_accounts, run_sync) with clear and predictable naming.

    Tool Count5/5

    13 tools cover a comprehensive range of personal finance operations without being excessive. Each tool serves a distinct and necessary function.

    Completeness4/5

    Covers holdings, investments, net worth, subscriptions, retirement, spending, merchants, bills, accounts, transactions, and sync. Missing budget management or transaction updating, but core data retrieval is well-covered.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      D
      quality
      C
      maintenance
      Turns a personal-finance SQLite database into typed, schema-validated tools that an AI assistant can call directly, letting you manage accounts, transactions, budgets, debts, investments, tax estimates, and goals through natural language.
      55
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to access and manage personal financial data from US institutions and manual entries, including transactions, balances, liabilities, and investments.
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Enables an agent to query local financial ledgers for expenses, investments, and income, with tools for savings rate, accounts, sync, and reconciliation.
      18
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables AI assistants to query and manage self-hosted accounting dataβ€”invoices, balances, and booksβ€”through natural language, with read-only tools by default and optional scoped write operations.
      30
      1
      AGPL 3.0