YNAB MCP Server

List transactions

list_transactions

Read-only

Retrieve YNAB transactions newest first and filter by date, amount, category, payee, status, or text to review spending and find specific entries.

Instructions

List transactions, newest first, with filters that can be combined.

Example queries this tool can answer:

"Show me all transactions over $50 in Dining Out this year" → category_id=, max_amount=-50, since_date=2024-01-01
"What do I still need to review?" → status="unapproved"
"What hasn't been categorized?" → status="uncategorized"
"How much did we spend at Amazon in March?" → payee_id=, since_date=2024-03-01, until_date=2024-03-31
"Find the soccer registration fee" → text_search="soccer"

Filtering by category or payee returns each part of a split transaction as its own row, with parent_transaction_id set.

Input Schema

Name	Required	Description
`limit`	No	Maximum number of transactions to return per page (default: 25)
`offset`	No	Number of transactions to skip for pagination (default: 0)
`status`	No	"unapproved" for transactions waiting for the user's review, or "uncategorized" for transactions with no category (optional)
`payee_id`	No	Only transactions with this payee (optional)
`account_id`	No	Only transactions in this account (optional)
`max_amount`	No	Only transactions with amount <= this, in currency units. Spending is negative, so -50 means "spent at least 50" (optional)
`min_amount`	No	Only transactions with amount >= this, in currency units. Spending is negative, so -50 means "spent at most 50" (optional)
`since_date`	No	Only transactions on or after this date (optional)
`until_date`	No	Only transactions on or before this date (optional)
`category_id`	No	Only transactions in this category (optional)
`text_search`	No	Only transactions whose payee name, memo, or original bank payee contains this text, ignoring case (optional)

Output Schema

Name	Required	Description	Default
`pagination`	Yes	Pagination information
`transactions`	Yes	List of transactions

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Oct 26, 2026

TDQS

A4.1/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds genuinely non-obvious behavior — newest-first ordering and that category/payee filters explode splits into separate rows with parent_transaction_id set. It doesn't discuss pagination limits or result size, but the key behavioral risk (split rows inflating counts) is disclosed.

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?

Purpose is front-loaded in one sentence, followed by scannable example mappings and a final caveat sentence. Each block earns its place; the examples are dense with mapping information rather than filler.

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?

With 11 optional params, an output schema present, and rich annotations, the description covers the remaining burden well: ordering, combinability, split-row behavior, and intent-to-parameter mapping. Only pagination/result-size expectations are left implicit.

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 description coverage is 100%, so baseline is 3, but the description adds value beyond the schema by showing parameter combinations in context (e.g., payee_id + date range for 'Amazon in March') and interpreting status values through intent questions. This is real semantic value the property docs alone don't convey.

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?

States a specific verb and resource plus ordering ('List transactions, newest first') and that filters combine. It doesn't explicitly distinguish itself from get_transaction, but the list-vs-single distinction is clear from the name pairing.

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?

Worked example queries map natural-language intents to concrete parameter sets, which tells an agent when this tool fits and how to configure it. It stops short of naming alternatives (e.g., get_transaction for a known ID) or stating exclusions, so it isn't full 5-level routing guidance.

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