What can you do with this server?

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

How do I use tuskledger-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. 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.

de en es ja ko ru zh

tuskledger-mcp

by BradMorphsters

Overview Schema Source Related Servers Discussions Admin

Python

Local

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.

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: Finance 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).

Project links

Main app: https://github.com/BradMorphsters/tuskledger
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 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.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A3.6/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must disclose all behavioral traits. It states it returns holdings across all accounts but does not mention performance, authentication requirements, or whether it triggers a refresh. Minimal extra context beyond obvious read operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences: first sets scope, second lists returned fields. No unnecessary words. Information is front-loaded and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a parameterless tool returning a list, the description covers the key output fields adequately. Lacks mention of potential size limits or ordering, but overall sufficient given simple use case.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Zero parameters, so schema coverage is 100%. Description adds value by detailing the output fields, which is necessary since no output schema exists. Baseline of 4 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states what the tool does: returns current investment holdings with specific fields (symbol, account, quantity, etc.) across all connected brokerages and 401(k)s. Distinguishes from sibling tools like get_investments_summary by emphasizing per-position detail.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs alternatives (e.g., get_investments_summary for aggregates). Does not specify preconditions or limitations such as requiring a recent sync.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden. It discloses the tool produces a summary roll-up (read-only behavior) and lists specific output fields. No contradictions; it is transparent for a simple, read-only tool with no parameters.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with key information, and no redundant words. Every sentence serves a purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters and no output schema, the description fully explains the output: total value, asset allocation, top 5 holdings, and YTD gain. An agent can confidently determine when to call this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters (schema coverage 100%), so baseline is 4. The description adds value by explaining what the tool returns, which is sufficient for the agent to understand usage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: a roll-up of investment portfolio including total value, asset allocation, top 5 holdings, and YTD gain. It also provides a usage hint ('the how are my investments doing? answer'), making it unambiguous and distinct from siblings like get_holdings or get_net_worth.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use this tool (for an overall portfolio snapshot), but does not explicitly mention when not to use or suggest alternatives. The context is clear but lacks explicit exclusion criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description	Default
`history`	No	If true, return the full snapshot history instead of just latest.

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description adds value by disclosing that numbers are point-in-time from last sync, not live-computed. It does not mention rate limits or auth, but for a read-only tool, this is acceptable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the main purpose, and every sentence adds value. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a low-complexity tool (one optional parameter, no output schema), the description explains the main output, data freshness, and a usage hint. It is mostly complete, though return format details are omitted.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema fully describes the single parameter 'history' with a description. The tool description does not add additional meaning beyond that, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns 'current net worth (assets minus liabilities) plus a 12-month trend', specifying the resource (net worth) and action (get). It distinguishes from siblings by noting data is point-in-time from last sync, not live-computed.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description tells when to use the tool to get net worth with trend and advises using list_stale_accounts to verify data freshness. It does not explicitly mention when not to use, but the sibling list provides context for alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It describes what the tool returns but does not explicitly state that it is read-only or disclose any potential side effects. The name and context strongly imply safety, but the description lacks explicit disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the main action, and every sentence adds value. No redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and zero parameters, the description adequately covers the tool's functionality by specifying return fields. However, it could offer more detail on detection confidence or limitations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the baseline is 4. The description adds value by listing the output fields, which helps the agent understand what data to expect, compensating for the lack of input parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it lists detected recurring subscriptions, provides concrete examples (Netflix, Spotify), and explicitly names the returned fields (merchant, cadence, etc.), making it distinct from siblings like get_upcoming_bills.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description includes a direct cue for common user queries ('what subscriptions do I have') and clearly indicates when to use the tool. However, it does not explicitly state when not to use or mention alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description
`current_age`	Yes	User's current age. Required.
`retirement_age`	No	Target retirement age (default 65).
`spouse_age`	No	Spouse's current age. Optional — enables two-phase simulation when paired with spouse_retirement_age.
`spouse_retirement_age`	No	Age at which the spouse retires (in spouse's years).
`desired_annual_income`	No	Target annual spending in retirement, today's dollars (default 80000).
`annual_contribution`	No	Annual contribution. Omit to auto-detect from last 12mo of investment-account inflows.
`return_rate`	No	Real annual return during accumulation (default 0.06 = 6%).
`withdrawal_rate`	No	Safe withdrawal rate (default 0.04 = the 4% rule).
`pension_annual`	No	Annual pension income, today's dollars.
`ss_annual`	No	Annual Social Security at the user's claim age.
`ss_start_age`	No	Age at which to claim SS (62–70, default 67).
`inflation_rate`	No	Long-run inflation assumption (default 0.025).

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, but the description discloses key behavior: it is a simulation (not a mutation), returns specific outputs, and depends on user-supplied data due to localStorage inaccessibility. It also mentions default assumptions (4% rule). No destructive or side effects indicated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured: first sentence states purpose, then details outputs and caveats. However, the third paragraph could be shortened slightly without losing clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 12 parameters and no output schema, the description adequately explains inputs, defaults, and output types (probability, depletion age, milestones). Could include more detail on milestone ages, but sufficient for an agent to invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema descriptions cover all 12 parameters with defaults, but the description adds context such as the 4% rule, two-phase simulation for spouses, and the option to pass known values to tighten projections. This adds value beyond the raw schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states 'Run the multi-decade Monte Carlo retirement simulator' and specifies outputs (probability of success, depletion age, summary at milestones). Distinct from sibling tools like get_investments_summary or get_net_worth, as it focuses on retirement projection.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear guidance: user must supply current_age because saved scenarios are not accessible; other parameters have sensible defaults. Mentions the localStorage limitation and suggests copying values from the UI. However, lacks explicit comparison to alternatives, though siblings are clearly different.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description
`start_date`	No	ISO date YYYY-MM-DD.
`end_date`	No	ISO date YYYY-MM-DD.
`exclude_business`	No	Drop transactions tagged as business (default false).

TDQS

B3.4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. It mentions default date range behavior and that it returns aggregated data, implying read-only. However, it does not explicitly state safety (e.g., no side effects) or authentication needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three concise sentences: first states the core function, second describes output format, third explains default behavior. No redundant words, front-loaded with the main purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 3 optional parameters and no output schema, the description explains return values (totals, subtotals, counts) but lacks details on structure (e.g., whether dates are inclusive) and does not mention the 'exclude_business' parameter. Could be more complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with clear parameter descriptions. The description adds value by specifying the default behavior for date range (current calendar month) when no dates are given, which is not in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool aggregates spending totals by category for a date range, returns totals, subtotals, and counts. It is distinct from siblings like 'query_transactions' but does not explicitly differentiate.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not provide guidance on when to use this tool versus alternatives like 'get_investments_summary' or 'query_transactions'. No exclusions or context for selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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?'.

ParametersJSON Schema

Name	Required	Description
`start_date`	No	ISO date.
`end_date`	No	ISO date.
`limit`	No	How many merchants to return (default 10).

TDQS

A3.6/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided. Description only lists return fields; does not disclose read-only nature, authentication requirements, rate limits, or behavior on empty results. Lacks behavioral context beyond output.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three concise sentences: purpose, output details, and a use case. No redundancy; front-loaded with actionable information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given low complexity and no output schema, description sufficiently covers return values. However, missing details such as sorting order (descending by spend?) and timezone handling could improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so description adds little beyond schema. Baseline 3; description's 'date range' and 'top N' mirror schema descriptions without enriching meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool returns top merchants by total spend in a date range, listing returned fields. It distinguishes itself from sibling tools like get_spending_summary by focusing on merchants.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides a use case ('who am I paying the most?') but lacks explicit guidance on when not to use or alternatives. No mention of sibling tools or conditions like data availability.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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?'.

ParametersJSON Schema

Name	Required	Description	Default
`days`	No	How many days forward to look (default 30).

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description carries the full burden. It discloses the output in detail (date, amount, source, projected balance) and implies read-only behavior. It could be improved by mentioning any prerequisites like synced accounts.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loading the main functionality and ending with a practical use case. Every sentence adds value with no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, no output schema), the description adequately covers what the tool does and returns. It addresses a common user question, leaving minimal gaps in understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a clear description for the single parameter 'days'. The description adds little beyond the schema's parameter description, so a baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns a forward 30-day calendar of expected bills and paychecks with a running balance. It specifies the verb ('returns') and the resource ('calendar of expected bills + paychecks'), distinguishing it from siblings like get_recurring_subscriptions or query_transactions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a clear use case: 'is my account going to dip before payday?'. However, it does not explicitly mention when not to use this tool or suggest alternatives among the siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses that the tool lists all accounts with selected fields and implies a read operation. However, it omits any mention of potential limitations (e.g., pagination, data freshness) or side effects. The description is adequate but not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences: the first clearly states output content, the second provides usage guidance. It is front-loaded and contains no unnecessary words, making it highly efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters, no output schema, and no annotations, the description is fairly complete. It states what is returned and when to use it. It does not address error conditions or scale limits, but for a simple list tool this is sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has no parameters and is 100% covered. The description adds no parameter-related meaning because there are none. Baseline for 0 parameters is 4, and the description appropriately focuses on output content.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses specific verb+resource ('List every connected account') and enumerates returned fields (balance, type, timestamp). It distinguishes from sibling tools by advising to use this first before drilling into transactions or holdings, clearly differentiating its purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use the tool ('Use this first to understand what accounts exist') and contrasts with drilling into transactions or holdings. It could be improved by explicitly noting when not to use it, but the guidance is clear enough.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses that the tool returns accounts based on freshness thresholds, which is the key behavioral trait. It implies a read-only operation, which is sufficient for a list tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no wasted words. The purpose is front-loaded, and the use case is given in the second sentence. Highly concise and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a parameterless tool with no output schema, the description adequately explains what the tool returns and when to use it. It is complete for the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has no parameters and schema coverage is 100%. The description does not need to add parameter info. Baseline 4 is appropriate as the description covers the tool's function without needing to detail parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: return accounts with stale data. It defines the freshness threshold (a week for synced, a month for manual) and distinguishes from siblings like list_accounts by focusing on stale accounts.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a specific use case: 'when the user asks why is my net worth wrong?' It implies this is for troubleshooting, not for a general list. However, it doesn't explicitly state when not to use it or mention alternatives, though siblings exist.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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).

ParametersJSON Schema

Name	Required	Description
`account_id`	No	Filter to a single account by id.
`category`	No	Filter to a single category name (exact match).
`start_date`	No	ISO date YYYY-MM-DD; inclusive lower bound.
`end_date`	No	ISO date YYYY-MM-DD; inclusive upper bound.
`limit`	No	Max rows to return (default 100, max 500).

TDQS

A3.6/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description covers default ordering, default limit, and common use cases. It does not disclose any potential side effects, authentication needs, rate limits, or the exact structure of returned data, but the behavioral context given is adequate for basic usage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the main purpose and uses bullet-like examples efficiently. Each sentence contributes meaning, though the examples could be slightly condensed without losing clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 5 parameters with full schema coverage, no output schema, and no annotations, the description covers ordering, filtering combos, defaults, and limits. It does not detail the return format, but for a list tool this is a minor gap; overall it is fairly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Despite 100% schema coverage, the description adds significant value by providing example combos (e.g., account_id + start_date + end_date) and clarifying defaults (limit default 100, max 500). This contextualizes parameters beyond the schema's standalone descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists transactions matching optional filters and returns the most recent first. It distinguishes from siblings by focusing on filtering and ordering, though it does not explicitly contrast with the similar-sounding 'search_transactions'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides common filter combinations and default behavior (no filter returns 100 recent transactions across all accounts). However, it lacks explicit guidance on when not to use this tool or alternatives (e.g., search_transactions for more complex queries), leaving usage implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description discloses the sync trigger, output summary, and safety due to deduplication. It doesn't mention rate limits or async behavior, but provides reasonable transparency for a simple action.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no wasted words. Front-loaded with the action verb and clear purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given zero parameters and no output schema, the description covers the essentials: trigger, return summary, and safety. Could mention sync duration but is sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, per instructions baseline is 4. No additional parameter info needed since schema coverage is complete.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it triggers a Plaid sync across all connected items, analogizes to UI Sync Now, and specifies the output summary. This distinguishes it from siblings which are all read-only query tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for syncing data but doesn't explicitly state when to prefer this over alternatives. It does convey that calling is safe and deduplication occurs, giving some usage confidence.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description	Default
`q`	Yes	Search string. Matches partial words, case-insensitive.
`limit`	No	Max rows (default 50).

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It mentions fuzzy matching and case-insensitivity but does not explicitly state the tool is read-only or describe result behavior beyond limit parameter. Returns a list of transactions, but no detail on ordering or that it doesn't modify data.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences front-load key purpose and usage boundaries. Every sentence adds value with zero repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple search tool with 2 parameters and no output schema, the description covers purpose, usage guidance, and search scope. Missing explicit mention that search is read-only and that results may be ordered by relevance, but overall adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema has 100% coverage of parameters (q and limit), and schema descriptions are adequate. Description adds minimal new info beyond schema (e.g., default limit 50 already in schema). No further enrichment needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it performs free-text search across transaction names, merchants, and notes. Provides specific example queries ('find that Whole Foods charge', 'when did I last pay Verizon?') and explicitly distinguishes from sibling tool query_transactions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly tells when to use this tool ('free-text search') and contrasts with query_transactions ('structured filter'). Includes concrete user expressions to guide invocation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

13 tool updatesv0.1.1May 17, 2026
- First observedget_holdings
- First observedget_investments_summary
- First observedget_net_worth
- First observedget_recurring_subscriptions
- First observedget_retirement_projection
- First observedget_spending_summary
- First observedget_top_merchants
- First observedget_upcoming_bills
- First observedlist_accounts
- First observedlist_stale_accounts
- First observedquery_transactions
- First observedrun_sync
- First observedsearch_transactions

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.1/5.0

Scored 2026-05-17 04:55 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.

Maintenance

ActivityStale

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

Era ContextOAuth
app.era
Personal finance, bank account, and shared memory connector for Claude, ChatGPT, Gemini Spark & more
Finance Knowledge & Memory
1
cashflowOAuth
io.github.adam-messinger
Personal finance ledger for AI agents — query spending, track bills, forecast cash flow.
Finance Databases
2
BankSyncOAuth
io.banksync
Connect AI agents to bank accounts, transactions, balances, and investments.
Finance Customer Data Platforms App Automation
22
Candor Finance AOAuth
money.candor
Personal-finance workspace for AI agents: accounts, spending, budgets, goals, and investments.
Agent Orchestration Finance
1112

Related MCP Servers

Lunch Money MCP Server
Finance App Automation
robshox
A
license
B
quality
D
maintenance
Enables AI agents to interact with your Lunch Money personal finance data, providing tools for managing transactions, categories, budgets, assets, and accounts.
Updated 5 months ago (2026-04-27 04:35 UTC)
15
13 npm
ISC
Finance MCP Server
Finance Databases
PavelKosik
A
license
Not graded
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.
Updated 3 months ago (2026-06-21 09:28 UTC)
24 npm
MIT
OpenBudget MCP Server
Finance Data Platforms
markets-ai
A
license
Not graded
quality
D
maintenance
Enables AI assistants to access and manage personal financial data from US institutions and manual entries, including transactions, balances, liabilities, and investments.
Updated 24 days ago (2026-08-22 10:57 UTC)
MIT
Finance Intelligence MCP
Finance Data Visualization Databases
Ronit-019
A
license
A
quality
A
maintenance
Enables AI assistants to securely manage and analyze personal finances through natural language, with full control over data via a private PostgreSQL database.
Updated 2 months ago (2026-07-04 14:00 UTC)
12
MIT

tuskledger-mcp

Quick context

What you can ask your assistant

What tools are available

Prerequisites

Install

Option A — uvx (recommended; no permanent install)

Option B — pip install from GitHub

Option C — clone for development

Where MCP client configs live

Configuration

Auth

What this server intentionally does NOT do

Troubleshooting

Development

Project links

Available Tools

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Option A — `uvx` (recommended; no permanent install)

Option B — `pip install` from GitHub