This server provides read-only access to YNAB budget data, plus an experimental, guarded write workflow for category assignments.
Read-only budget inspection: List plans, get budget snapshots, view accounts, categories, transactions, scheduled transactions, and payees.
Focused filtering: Filter transactions by date, account, category, payee, cleared status, approval status, and more; list scheduled transactions within a date range.
Assignment preview (no changes): Validate and preview category assignment changes without applying them.
Apply only with explicit approval: Apply a previously approved assignment preview, but only if the server is started with YNAB_ENABLE_WRITES=true and a valid preview token.
Safety and control: All read operations are read-only; writes require user approval and strict environment conditions.
No telemetry or storage: The server runs locally and does not store data.
Click on "Install 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., "@YNAB Budget MCP Which categories are overspent 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.
A local Model Context Protocol server that gives AI assistants a focused, guarded way to understand YNAB budget data.
Use this when you want an MCP-capable assistant to help you understand your YNAB budget without giving it unrestricted control. It can inspect plans, budget snapshots, accounts, categories, transactions, scheduled transactions, and payees. It is not financial advice and does not replace your own review of your budget.
Examples of useful requests include:
“Which categories are overspent this month?”
“Show my uncategorized transactions from the last two weeks.”
“What scheduled transactions are due in the next 30 days?”
“Preview assigning $100 to Groceries, but do not apply it.”
All budget reads and assignment previews are read-only. The only write capability is an intentionally narrow, experimental category-assignment workflow:
Your assistant creates a preview containing the exact category changes, before/after Ready to Assign, remaining uncovered categories, and relevant cross-month effects.
You review and explicitly approve that exact preview.
Applying it additionally requires YNAB_ENABLE_WRITES=true, a fresh single-use token, and an unchanged YNAB state.
An assignment preview can intentionally leave categories overspent or a month with negative Ready to Assign. Those states are never treated as available money: the preview reports them as warnings and lists each remaining uncovered category and amount. This allows a deliberate partial assignment (for example, protecting an imminent bill) or a future-month reallocation while keeping the risk visible for approval.
The server runs locally, sends requests directly to YNAB, and has no telemetry or persistent storage.
You need Node.js 22.9+ and a YNAB Personal Access Token from YNAB developer settings.
If your AI assistant supports local stdio MCP servers, copy and paste this prompt into it. The linked README is the source of truth; the agent should use the instructions for its own client.
Please install YNAB Budget MCP for me, following the canonical instructions at https://github.com/Orlando-Villanueva/ynab-budget-mcp#connect-it-to-your-assistant.
Use the published npm package, not a repository clone or local source checkout. Follow the generic terminal setup unless this is Codex, in which case use the Codex CLI or Codex app instructions. When the MCP configuration requires my YNAB token, stop and tell me to enter it myself in this client's MCP server Environment variables or Secrets field, using the exact key `YNAB_ACCESS_TOKEN`. Do not ask me to paste the token into chat, a command, a project file, or any shared configuration. Leave `YNAB_ENABLE_WRITES` unset. When setup is complete, tell me how to verify the MCP connected successfully.Install the published package:
npm install -g ynab-budget-mcp@betaThen add a local stdio MCP server in your assistant's settings with:
Field | Value |
Command |
|
Environment variable or secret |
|
Working directory | Leave blank |
Enter the token in the assistant's MCP Environment variables or Secrets field—not in a repository .env file, an issue, a screenshot, or a chat message. Every MCP client labels this screen differently, but the variable name is always YNAB_ACCESS_TOKEN.
If your MCP client uses JSON configuration, this is the generic server definition:
{
"command": "ynab-mcp",
"env": {
"YNAB_ACCESS_TOKEN": "your-token"
}
}In Terminal, run the following. It uses a hidden token prompt, then saves a local Codex MCP configuration without requiring a repository checkout:
read -s "YNAB_ACCESS_TOKEN?Paste your YNAB access token: "
echo
codex mcp add ynab \
--env "YNAB_ACCESS_TOKEN=$YNAB_ACCESS_TOKEN" \
-- npx -y ynab-budget-mcp@beta
unset YNAB_ACCESS_TOKENRestart Codex, then run codex mcp get ynab to confirm the server is configured.
In Codex, open Plugins, choose Add → MCP server, and create a stdio server with these values:
Field | Value |
Command |
|
Arguments |
|
Environment variable |
|
Working directory | Leave blank |
Save the server and restart Codex. This downloads the published package when needed; no repository clone, local .env, or global installation is required.
If you prefer not to install globally, configure your client to run npx -y ynab-budget-mcp@beta instead. The following JSON is one generic example; it is not a Codex configuration file:
{
"command": "npx",
"args": ["-y", "ynab-budget-mcp@beta"],
"env": {
"YNAB_ACCESS_TOKEN": "your-token"
}
}Keep the token private. It grants access to the YNAB data available to it; never add it to a repository, issue, screenshot, or shared configuration file.
Related MCP server: YNAB Assistant
This section is for working on the MCP itself rather than simply using it with an assistant.
Clone the repository, install its development dependencies, and create a local token file:
git clone https://github.com/Orlando-Villanueva/ynab-budget-mcp.git
cd ynab-budget-mcp
npm ci
cp .env.example .envSet YNAB_ACCESS_TOKEN in your uncommitted .env. To permit a real, explicitly approved assignment apply during a local session, also set YNAB_ENABLE_WRITES=true; leave it unset for normal development and testing.
Start the local stdio server with:
npm run startFor an MCP client to use your source checkout directly, configure it with a portable path and working directory:
{
"command": "node",
"args": [
"--env-file-if-exists=.env",
"--experimental-transform-types",
"src/index.ts"
],
"cwd": "/absolute/path/to/ynab-budget-mcp"
}This local-development configuration is separate from the published-package setup above. You can keep using an installed release while developing changes in another checkout.
npm test
npm run checknpm run check builds the package and runs the test suite. The project intentionally has no runtime dependencies; TypeScript build tools are development-only.
See SECURITY.md for security and privacy expectations, and SUPPORT.md for support expectations.
This project is not affiliated with, endorsed by, or sponsored by YNAB. YNAB is a trademark of its respective owner.
Apply a short-lived assignment preview token only after the user explicitly approves the exact preview.
| Name | Required | Description | Default |
|---|---|---|---|
| preview_token | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is not read-only and not idempotent. The description adds that the token is short-lived and requires explicit approval, but it does not explain the side effects of applying or whether the operation is reversible. This is useful but limited context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It efficiently communicates the action and the required condition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple one-parameter mutation without an output schema, but the description omits side effects, return value, and error conditions. It is adequate for basic understanding but incomplete for an agent to fully predict the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema_description_coverage at 0%, the description needed to provide meaning for the preview_token parameter. It only says 'short-lived assignment preview token,' which largely restates the parameter name. No format, origin, or validity details are given, so the agent must infer from the name alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool applies a short-lived assignment preview token, and specifies the exact condition ('only after the user explicitly approves the exact preview'). This distinguishes it from the sibling tool ynab_preview_assignments, which creates the preview.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit usage condition: use only after user approval. It implies this is the follow-up step to previewing assignments, but it does not explicitly name alternative tools or state when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a high-level snapshot of a YNAB plan for a given month, including month details, account totals, and category highlights.
| Name | Required | Description | Default |
|---|---|---|---|
| month | No | Budget month in YYYY-MM format. Defaults to the current month. | |
| plan_id | No | YNAB plan id. Defaults to "default". | |
| refresh | No | Bypass TTL and delta baselines and fetch a complete response. Defaults to false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds the month scoping and content areas but does not disclose behavioral traits such as caching, refresh behavior, or return format. Since annotations handle the main safety context, a score of 3 is appropriate, consistent with examples where the description adds some value but not rich behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the main purpose and lists the key output components. Every phrase adds value without redundancy. It is concise and immediately informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description gives a reasonable outline of the expected return content ('month details, account totals, and category highlights'), which is sufficient for a snapshot tool. Combined with solid annotations and full schema coverage, the context is fairly complete, though it could have clarified the refresh/TTL behavior beyond the schema parameter description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter (month, plan_id, refresh) clearly documented. The tool description itself adds minimal parameter meaning beyond the schema, only reinforcing the 'given month' aspect. With high schema coverage, the baseline of 3 applies; the description does not compensate further.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('Get') and resource ('a high-level snapshot of a YNAB plan for a given month'), and lists the included aspects (month details, account totals, category highlights). This distinguishes it from sibling tools like ynab_list_accounts or ynab_list_categories, which provide detailed lists rather than a combined snapshot.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies appropriate usage: when seeking a high-level monthly summary rather than granular details. It does not explicitly mention alternatives or when-not-to-use, but the phrase 'high-level snapshot' and the month scoping provide clear context. No exclusions are stated, but the sibling tool names hint at more detailed options.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one exact category for one exact YNAB plan month.
| Name | Required | Description | Default |
|---|---|---|---|
| month | Yes | ||
| plan_id | No | YNAB plan id. Defaults to "default". | |
| refresh | No | Bypass TTL and delta baselines and fetch a complete response. Defaults to false. | |
| category_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is well covered. The description adds the scoping constraint ('one exact category for one exact month') but no additional behavioral context such as caching, staleness, rate limits, or response characteristics. This is acceptable given the annotations but adds minimal value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that immediately conveys the core purpose without any filler. It is front-loaded and perfectly sized for the simplicity of the operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 4 parameters, no output schema, and a set of sibling tools, the description is under-specified. It does not explain the return value, how this tool differs from ynab_list_categories in practical terms, or the meaning of refresh beyond the schema. The minimal wording leaves the agent with gaps in understanding when to invoke this tool and what to expect in the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%: plan_id and refresh have descriptions, while month and category_id do not. The description indirectly clarifies that month refers to a YNAB plan month and category_id refers to a category, but it does not provide format details beyond the schema's regex pattern for month or explain the relationship between category_id and the plan. The description adds some context but fails to fully compensate for the undocumented required parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get'), the resource ('category'), and the scope ('one exact category for one exact YNAB plan month'). This distinguishes it from sibling tools like ynab_list_categories, which would list multiple categories. The use of 'exact' reinforces the single-item retrieval purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as ynab_list_categories or ynab_get_budget_snapshot. It does not mention any exclusions, prerequisites, or selection criteria, leaving the agent to infer usage solely from the tool name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List accounts for a YNAB plan.
| Name | Required | Description | Default |
|---|---|---|---|
| plan_id | No | YNAB plan id. Defaults to "default". | |
| refresh | No | Bypass TTL and delta baselines and fetch a complete response. Defaults to false. | |
| include_closed | No | Include closed accounts. Defaults to false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, which cover the safety profile. The description adds no additional behavioral context (e.g., caching, TTL, or result completeness), but this is acceptable given the simple list operation and strong annotation coverage. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no waste. It immediately states the tool's core function. Despite being minimal, it is appropriately sized for a simple read-only list operation and holds no redundant phrases.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (three optional parameters, no output schema) and the strong schema/annotation coverage, the description is mostly complete for a simple list tool. It describes the primary purpose accurately, and the schema covers default values and refresh behavior. However, it does not explicitly mention that closed accounts are excluded by default, which is a meaningful contextual detail, but not critical for the agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description itself adds no parameter-level meaning beyond what the schema already provides, but it does not need to since each parameter is well-documented. The description's generic 'list' framing does not enhance or deviate from schema semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and resource ('accounts for a YNAB plan'), which distinguishes it from sibling listing tools like list_categories or list_transactions. However, it does not explicitly mention optional behaviors like including closed accounts, which the schema describes, so it slightly underestimates the tool's full purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention exclusions, related tools, or scenarios where another tool would be better suited. This leaves the agent without behavioral context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List category groups and categories for a YNAB plan, with optional month context.
| Name | Required | Description | Default |
|---|---|---|---|
| month | No | Optional budget month in YYYY-MM format. | |
| plan_id | No | YNAB plan id. Defaults to "default". | |
| refresh | No | Bypass TTL and delta baselines and fetch a complete response. Defaults to false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds 'optional month context', which is already present in the schema parameter description, so it adds limited new behavioral context. It does not mention the refresh parameter's TTL bypass behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one sentence, front-loaded with the action, and contains no unnecessary words. It is concise and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple listing tool with three optional parameters, the description combined with full schema and annotations is mostly complete. It tells the agent what the tool returns and the month context. However, it does not distinguish from the similar ynab_get_month_category or explain the month's effect on the response, so it is not fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and each parameter has its own description. The tool description adds no new meaning beyond the schema, merely echoing the month parameter with 'optional month context'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' with the resource 'category groups and categories' for a YNAB plan, clearly stating what the tool does. It differentiates from sibling tools like ynab_list_accounts and ynab_list_transactions by focusing on categories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing categories but provides no explicit guidance on when to use this tool versus alternatives such as ynab_get_month_category. There are no exclusions or alternative tool mentions, so guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List payees for a YNAB plan.
| Name | Required | Description | Default |
|---|---|---|---|
| plan_id | No | YNAB plan id. Defaults to "default". | |
| refresh | No | Bypass TTL and delta baselines and fetch a complete response. Defaults to false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the agent knows this is a safe read-only operation. The description adds no extra behavioral context such as pagination, rate limits, or return format. It only restates the scope, so it adds minimal value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence: 'List payees for a YNAB plan.' It is front-loaded with the verb and resource, contains no fluff or repetition, and is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple list operation with two optional parameters, high schema coverage, and strong read-only annotations. The description sufficiently states the purpose, and the schema covers parameter defaults and refresh behavior. No output schema exists, so return-value details are not needed. The description is complete enough for an agent to select and invoke the tool successfully.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for both parameters (plan_id and refresh), each with clear descriptions. The description 'List payees for a YNAB plan' does not add any additional parameter semantics, but the schema already covers the default and refresh behavior, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'payees', scoped to 'a YNAB plan'. This is specific enough to distinguish from sibling list tools like ynab_list_accounts or ynab_list_categories, even though it doesn't name them. The title adds no additional confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention any prerequisites, filtering preferences, or references to sibling tools. An agent would have to infer usage purely from the resource name, which gives no comparative context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the YNAB plans available to the configured token.
| Name | Required | Description | Default |
|---|---|---|---|
| refresh | No | Bypass TTL and delta baselines and fetch a complete response. Defaults to false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds that results are scoped to the configured token, which is useful context. However, it does not disclose any additional behavior such as caching, request cost, or response structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is directly front-loaded with the action and resource. Every word earns its place, with no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with rich annotations and a single well-documented parameter, the description is adequate. It clearly states the tool's purpose and scope, though without an output schema it could be slightly more explicit about what 'plans' includes or the response format. Given the low complexity, this minor gap is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'refresh' is fully described in the schema (100% coverage), so the description need not repeat it. The description adds no additional meaning beyond the schema, which is acceptable given the schema already explains the parameter well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List the YNAB plans available to the configured token' clearly states the verb (list), resource (YNAB plans), and scope (available to the configured token), distinguishing it from sibling list tools like ynab_list_accounts or ynab_list_transactions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description does not mention any prerequisites, context, or exclusions, leaving the agent to infer the appropriate usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List and project scheduled YNAB transaction occurrences through a bounded date horizon.
| Name | Required | Description | Default |
|---|---|---|---|
| plan_id | No | YNAB plan id. Defaults to "default". | |
| refresh | No | Bypass TTL and delta baselines and fetch a complete response. Defaults to false. | |
| payee_id | No | ||
| from_date | Yes | ||
| account_id | No | ||
| category_id | No | ||
| through_date | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, which cover safety and idempotency. The description adds the 'bounded date horizon' scoping, but it does not explain how projection works, whether pagination exists, or what GET-like behavior is expected. Beyond the annotations, the added behavioral context is minimal but non-contradictory.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It states the action and scope directly, earning its place. While it is brief, it is not verbose and is appropriately concise for its purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite good annotations, the tool has 7 parameters, no output schema, and a description that lacks details on the returned data structure, how 'project' is computed, and how filters affect results. The description is too high-level to give an agent a complete understanding of the tool's behavior without further inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 29%, with most parameters (payee_id, account_id, category_id) lacking descriptions. The description only hints at date bounding and does not elaborate on the meaning of individual parameters or how they interact with the date range. It fails to compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs ('list and project') and a clear resource ('scheduled YNAB transactions') with a scope ('bounded date horizon'). The inclusion of 'scheduled' distinguishes it from the sibling tool ynab_list_transactions, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for scheduled/projected transactions through the word 'scheduled' and the date horizon, but it does not explicitly state when to use this tool versus ynab_list_transactions or mention any alternative. No when-not-to-use guidance or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List transactions for a YNAB plan with optional date, month, account, category, payee, and limit filters.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | YNAB-supported server-side cleanup filter. | |
| limit | No | Maximum number of transactions to return. Defaults to 100. | |
| month | No | Only keep transactions in the given YYYY-MM month. | |
| offset | No | Number of matching transactions to skip. Defaults to 0. | |
| cleared | No | Optional local cleared-status filter. | |
| plan_id | No | YNAB plan id. Defaults to "default". | |
| refresh | No | Bypass TTL and delta baselines and fetch a complete response. Defaults to false. | |
| approved | No | Optional local approved-status filter. | |
| payee_id | No | Optional payee id filter. | |
| all_dates | No | Query from the plan's first month. Mutually exclusive with since_date and month. | |
| account_id | No | Optional account id filter. | |
| since_date | No | Only return transactions on or after YYYY-MM-DD. | |
| until_date | No | Only return transactions on or before YYYY-MM-DD. | |
| category_id | No | Optional category id filter. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds little beyond the schema (e.g., mentioning filters), and does not disclose details like pagination or caching behavior beyond what the schema already states.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It immediately conveys the action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich input schema (14 params, all described) and annotations covering safety, the description is mostly sufficient. It omits mention of pagination or the full range of filters, but the schema fills those gaps. It could improve by noting pagination or that it returns actual transactions vs. scheduled.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description names only a subset of filters (date, month, account, category, payee, limit) and adds no meaning beyond the schema's own parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists transactions for a YNAB plan, using a specific verb and resource. It is easily distinguished from siblings like ynab_list_plans or ynab_list_scheduled_transactions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it lists transactions with various optional filters. However, it does not explicitly mention when not to use this tool (e.g., when scheduled transactions are needed) or reference alternatives, leaving the guidance implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Freshly validate exact category assignment deltas and create a short-lived preview token without changing YNAB.
| Name | Required | Description | Default |
|---|---|---|---|
| month | Yes | ||
| plan_id | No | YNAB plan id. Defaults to "default". | |
| assignments | Yes | ||
| guard_month | No | Required for future-month assignments; constrains usable funds. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavior beyond annotations: it reveals the tool creates a 'short-lived preview token' and validates 'freshly', implying live state checks. The 'without changing YNAB' aligns with readOnlyHint=true and destructiveHint=false. No contradictions found. It could further explain token expiry or usage, but the added context is meaningful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, tightly worded sentence that front-loads the action ('Freshly validate') and conveys mode, purpose, and safety in under 20 words. Every phrase earns its place with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description hints at the return value ('short-lived preview token') but does not describe its format or how it integrates with sibling tools like ynab_apply_assignment_preview. The complexity is moderate, but the tool's purpose and primary outcome are clear, and the sibling list supplies enough context to infer usage. Slightly more detail on token validity or validation failure would push it to 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (plan_id and guard_month are described; month and assignments are not). The description's reference to 'exact category assignment deltas' clarifies the assignments parameter, and 'validate' implies the tool checks these deltas. However, it does not compensate for all undocumented parameters (e.g., month format or category_id semantics), leaving the schema to carry half the burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs ('validate', 'create') and a clear resource ('exact category assignment deltas') plus a concrete output ('short-lived preview token'). It explicitly states 'without changing YNAB', distinguishing it from sibling tools like ynab_apply_assignment_preview. This is a precise and unambiguous purpose statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'without changing YNAB' implies this is the safe, non-destructive alternative to applying assignments, providing clear context for when to use it. However, it does not explicitly name alternatives or state 'use this when you want to validate before applying', so it stops short of a full when/when-not guide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool targets a distinct resource or action: plans, budget snapshots, accounts, categories, transactions, scheduled transactions, payees, and assignment preview/apply. Even the category-related tools are clearly separated by scope (list vs single snapshot vs exact month detail).
All tools follow a consistent ynab_verb_noun pattern, e.g., ynab_list_transactions, ynab_get_month_category, ynab_preview_assignments. The minor variation between 'preview_assignments' and 'apply_assignment_preview' still fits the verb_noun structure with compound nouns.
10 tools is well within the ideal range for a domain-specific MCP server. Each tool covers a meaningful atomic operation without unnecessary bloat, making the surface easy to navigate.
The read surface is strong, covering plans, accounts, categories, transactions, scheduled transactions, and payees, plus a write path for assignment preview/apply. However, there are notable gaps: no create/update/delete for transactions or accounts, and no way to modify categories other than via assignments. Agents needing full budget management would encounter dead ends.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Log, query, and edit expenses, budgets, and accounts in Ledgy from any MCP-compatible AI assistant.
Log, query, and edit expenses, budgets, and accounts in Manilo (formerly Ledgy) from any MCP-compatible AI assistant.
Personal-finance workspace for AI agents: accounts, spending, budgets, goals, and investments.
Chat with your bank data: balances, transactions, budgets, bills. Reads only, never moves money.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Orlando-Villanueva/ynab-budget-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server