tuskledger-mcp
This server provides an MCP bridge to read and analyze your local Tusk Ledger personal finance data, enabling an AI assistant to answer questions about your finances without sending data off your machine.
Accounts
List all connected accounts with balances, types, and last-sync timestamps
Identify stale accounts with outdated data
Transactions
Filter transactions by account, category, and/or date range (up to 500 results)
Free-text fuzzy search across transaction names, merchants, and notes
Spending Insights
Aggregated spending by category for a given date range
Top merchants by total spend with transaction counts and monthly trends
Detect recurring subscriptions (e.g. Netflix, Spotify) with cadence and next expected date
View budget limits and over/under status
Cash Flow & Bills
30-day forward calendar of upcoming bills and paychecks with a projected running balance
Broader cash flow forecasting
Net Worth & Investments
Current net worth (assets minus liabilities) with optional 12-month historical trend
All investment holdings across brokerages and 401(k)s with symbol, quantity, value, and unrealized gain/loss
Portfolio summary including asset allocation, top holdings, and YTD gain
Taxes & Retirement
Trading tax summary using FIFO accounting with wash sale detection
Multi-decade Monte Carlo retirement simulation returning probability of success, depletion age, and milestone summaries
Operations
Trigger a Plaid sync to refresh all connected accounts
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@tuskledger-mcp Show me my top spending categories this month"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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 |
|
Transactions |
|
Spending insight |
|
Cash flow |
|
Budgets |
|
Net worth & investments |
|
Taxes & planning |
|
Ops |
|
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:8000The 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-mcpThen 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) |
|
Claude Desktop (Windows) |
|
Cursor | Settings β Features β Model Context Protocol β paste the same |
Cowork | Same |
Claude Code | Project-level |
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 |
|
| Where your Tusk Ledger backend listens. Override if you've moved the port. |
|
| 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/ -vThe 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).
Project links
Project site: https://www.tuskledger.com
For agents browsing externally: https://www.tuskledger.com/llms.txt
Issues / discussions: https://github.com/BradMorphsters/tuskledger-mcp/issues
License: MIT
Available Tools
13 toolsget_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
Scored across 13 tools
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.
All tools follow a consistent verb_noun pattern (e.g., get_holdings, list_accounts, run_sync) with clear and predictable naming.
13 tools cover a comprehensive range of personal finance operations without being excessive. Each tool serves a distinct and necessary function.
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
Personal finance, bank account, and shared memory connector for Claude, ChatGPT, Gemini Spark & more
Personal finance ledger for AI agents β query spending, track bills, forecast cash flow.
Connect AI agents to bank accounts, transactions, balances, and investments.
Read-only access to your own bank, card and brokerage accounts for Claude, ChatGPT and other AI agents: balances, transactions, spending, subscriptions, cashflow and investment holdings. It can never move money.
Related MCP Servers
- AlicenseDqualityCmaintenanceTurns 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.55MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to access and manage personal financial data from US institutions and manual entries, including transactions, balances, liabilities, and investments.MIT
- AlicenseBqualityDmaintenanceEnables an agent to query local financial ledgers for expenses, investments, and income, with tools for savings rate, accounts, sync, and reconciliation.18MIT
- AlicenseBqualityCmaintenanceEnables 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.301AGPL 3.0