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-mcp show me my recent transactions"
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.
An MCP server that exposes your YNAB (You Need A Budget) budget to MCP clients such as Claude Desktop and claude.ai.
Read
ynab_list_budgets — budgets accessible with your token
ynab_list_accounts — accounts and balances of a budget
ynab_list_categories — category groups with budgeted / activity / balance
ynab_list_payees — payees (paginated)
ynab_list_transactions — transactions with filters (account, category, date, type)
ynab_get_budget_month — monthly summary (to-be-budgeted, income, activity, age of money)
Write
ynab_create_transaction — create a transaction (amount in currency units, negative = expense)
ynab_update_transaction — partially update a transaction (categorize, approve, memo…)
Related MCP server: YNAB Assistant
A YNAB Personal Access Token — YNAB → Account Settings → Developer Settings → New Token
uv sync # install dependencies
cp .env.example .env # then put your token in .env.env:
YNAB_TOKEN=your-token-here
YNAB_BUDGET_ID= # optional; empty = use YNAB's "last-used" budgetRun it:
uv run ynab-mcpAdd to your claude_desktop_config.json:
{
"mcpServers": {
"ynab": {
"command": "uv",
"args": ["run", "--directory", "/absolute/path/to/ynab-mcp", "ynab-mcp"],
"env": { "YNAB_TOKEN": "your-token-here" }
}
}
}Set MCP_TRANSPORT=http to serve over streamable-http (endpoint /mcp):
MCP_TRANSPORT=http HOST=0.0.0.0 PORT=8000 uv run ynab-mcpThis server is built with the fastmcp package, so
it deploys as-is on FastMCP Cloud:
Push this repo to GitHub, then connect it as a project on fastmcp.cloud.
Set the entrypoint to src/ynab_mcp/server.py:mcp.
Add YNAB_TOKEN (and optionally YNAB_BUDGET_ID) as an environment
variable/secret in the project settings — dependencies are picked up
automatically from pyproject.toml.
You can validate the entrypoint locally first:
uv run fastmcp inspect src/ynab_mcp/server.py:mcpAmounts are in normal currency units; an expense is negative (e.g. -12.50).
Conversion to/from YNAB milliunits is automatic.
budget_id defaults to YNAB_BUDGET_ID, or the "last-used" budget if unset.
YNAB rate limit: 200 requests / hour / token.
uv sync --extra dev
uv run pytest # tests (HTTP mocked, no network)
uv run ruff check . # lintNever commit .env — it contains a live token and is gitignored. If a token
leaks, rotate it in YNAB's Developer Settings.
MIT
Create a transaction in an account.
The amount is given in normal currency units (e.g. -12.50 for a 12.50 expense); conversion to milliunits is automatic. Returns the new id.
| Name | Required | Description | Default |
|---|---|---|---|
| memo | No | Free-form memo | |
| amount | Yes | Amount in currency units. NEGATIVE for an expense, positive for income. E.g. -12.50 | |
| cleared | No | 'cleared', 'uncleared' or 'reconciled' | uncleared |
| approved | No | Mark as approved | |
| txn_date | No | Date YYYY-MM-DD (default: today) | |
| budget_id | No | Budget id, or 'last-used' | last-used |
| account_id | Yes | Target account (required) | |
| payee_name | No | Payee name (created if it does not exist) | |
| category_id | No | Category to assign |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that amount conversion to milliunits is automatic and that the new id is returned, adding value beyond annotations. No contradictions with 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?
Two sentences cover the core action and key behavior (conversion, return value), but could be more structured with bullet points for readability.
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 output schema exists and the description mentions the returned id, it is fairly complete. However, it does not mention other potential response fields or error conditions.
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 coverage is 100%, but the description adds useful context about amount units and conversion, which aids correct usage beyond the schema 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 action ('Create') and the resource ('a transaction in an account'), which is specific and distinguishes it from sibling tools like 'list' or 'update'.
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?
While the purpose is clear, the description does not provide explicit guidance on when to use this tool versus alternatives, nor does it mention prerequisites or context like needing account_id.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Budget summary for a month: to be budgeted, income, budgeted, activity, age of money.
| Name | Required | Description | Default |
|---|---|---|---|
| month | No | 'current' or a month as YYYY-MM-01 | current |
| budget_id | No | Budget id, or 'last-used' | last-used |
| response_format | No | How a tool should render its result. | markdown |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds specific fields returned (to be budgeted, income, etc.), providing additional behavioral context 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?
Single sentence, front-loaded with key purpose, no wasted words. Ideal conciseness.
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 presence of an output schema and rich annotations, the description provides sufficient context for this simple read operation. Minimal gaps.
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?
Input schema has 100% description coverage for all three parameters. The tool description does not add new parameter meaning beyond what the schema provides, baseline score 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?
Description clearly states the tool retrieves a budget summary for a month, listing specific fields like 'to be budgeted', 'income', 'budgeted', 'activity', 'age of money'. It is distinct from sibling tools which handle transactions, accounts, etc.
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 explicit guidance on when to use this tool versus alternatives. The context from sibling names implies it is for month summary retrieval, but no when-not-to-use or alternative suggestions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List a budget's accounts with their balance (converted to currency units).
Returns: id, name, type, on_budget (bool), current balance, closed flag.
| Name | Required | Description | Default |
|---|---|---|---|
| budget_id | No | Budget id, or 'last-used' | last-used |
| include_closed | No | Include closed accounts | |
| response_format | No | How a tool should render its result. | markdown |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds value by specifying that balances are converted to currency units and listing the return fields (id, name, type, etc.), providing behavioral context beyond the structured 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 extremely concise with two sentences: one stating the core purpose and one listing return fields. No redundant information, every word earns its place.
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 description covers the main functionality and key return fields. An output schema exists, so the description need not fully detail returns. It is complete for a simple list tool, though it could mention if closed accounts are included by default (handled by parameter).
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 clear parameter descriptions (budget_id, include_closed, response_format). The description does not add significant extra meaning beyond the schema, aligning with the baseline score of 3.
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 'List a budget's accounts with their balance (converted to currency units)', providing a specific verb ('List') and resource ('accounts'). It distinguishes from sibling tools like ynab_list_budgets, ynab_list_categories, etc. by focusing on accounts.
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 indicates the tool lists accounts but does not explicitly state when to use it vs alternatives or when not to use it. The context is clear from the name and sibling tools, but no exclusions or conditions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the YNAB budgets accessible with this token, with their currency.
Returns for each budget: id, name, currency iso_code, last modified date. Useful to grab a specific budget_id (otherwise use "last-used" elsewhere).
| Name | Required | Description | Default |
|---|---|---|---|
| response_format | No | How a tool should render its result. | markdown |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety and idempotency. The description adds value by detailing the return fields and behavior (accessible with token), complementing annotations without contradiction.
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 three sentences: first states purpose, second lists return fields, third gives usage guidance. It is concise, front-loaded, and every sentence adds value without redundancy.
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 presence of an output schema and strong annotations, the description sufficiently covers what the tool returns and how to use it. It lists key fields and provides a usage hint, making it complete for a list tool.
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 coverage is 100% with a description for the single parameter 'response_format'. The description does not add further semantic meaning beyond the schema, meeting baseline 3 as per rules.
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 'YNAB budgets', specifies what is returned (id, name, currency, last modified), and distinguishes from sibling list tools by focusing on budgets. The mention of 'last-used' as an alternative further clarifies 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 a clear use case: 'Useful to grab a specific budget_id' and mentions an alternative ('otherwise use last-used elsewhere'), giving context for when to use this tool. However, it does not explicitly compare to other siblings or state when not to use it.
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 their categories, with budgeted / activity / balance.
Each category: id, name, budgeted, activity, balance (all in currency units). Needed to grab a category_id before creating/categorizing a transaction.
| Name | Required | Description | Default |
|---|---|---|---|
| budget_id | No | Budget id, or 'last-used' | last-used |
| response_format | No | How a tool should render its result. | markdown |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds value by noting the included fields (id, name, budgeted, activity, balance) but does not disclose additional behavioral traits beyond what annotations provide.
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?
Two concise sentences: the first states the main purpose and output details, the second explains why it's useful. No extraneous information.
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 presence of an output schema (context signals) and the clear read-only nature of the tool, the description covers the essential information (return fields, usage purpose) without needing to explain return values in detail.
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 coverage is 100% with both parameters ('budget_id', 'response_format') having descriptions in the input schema. The description does not add significant meaning beyond schema defaults, so baseline 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 it lists category groups and categories with budgeted/activity/balance, and specifically mentions it's needed to obtain a category_id for transactions, distinguishing it from siblings like 'ynab_list_accounts' or 'ynab_list_budgets'.
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 explicitly says the tool is needed to grab a category_id before creating or categorizing a transaction, providing clear usage context. However, it does not explicitly mention when not to use it or suggest alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List a budget's payees, paginated.
Returns id + name. Useful to find the id of a recurring merchant.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results | |
| offset | No | Pagination offset | |
| budget_id | No | Budget id, or 'last-used' | last-used |
| response_format | No | How a tool should render its result. | markdown |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 description does not need to reiterate safety. It adds 'paginated' and 'Returns id + name' which are helpful but not essential beyond annotations. No contradictions.
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?
Two sentences with no wasted words. The description is front-loaded with the action and pagination, then a note on return values and use case. Every sentence adds value.
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 pagination and an existing output schema, the description covers purpose, pagination, return fields, and a use case. It is complete and leaves no obvious gaps.
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 documentation covers 100% of parameters with descriptions. The tool description adds 'List a budget's payees' and 'Returns id + name' but does not enhance parameter meaning beyond the schema. Baseline 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 'List a budget's payees, paginated.' with a specific verb and resource. It distinguishes from sibling tools like ynab_list_accounts and ynab_list_budgets by focusing on payees. The additional note 'Useful to find the id of a recurring merchant' provides a concrete use case.
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 finding payee IDs via 'Useful to find the id of a recurring merchant,' but lacks explicit when-to-use or when-not-to-use guidance compared to alternatives. Given no sibling tool lists payees, it 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 a budget's transactions, with filters and pagination.
Filter by account OR by category (not both, per the API), by date (since_date) and by type (uncategorized / unapproved). Amount is in currency units (negative = expense). Returns id, date, payee_name, amount, category_name, memo, approved, cleared.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results | |
| offset | No | Pagination offset | |
| txn_type | No | 'uncategorized' or 'unapproved' to return only those | |
| budget_id | No | Budget id, or 'last-used' | last-used |
| account_id | No | Filter by account | |
| since_date | No | Only since this date, format YYYY-MM-DD | |
| category_id | No | Filter by category | |
| response_format | No | How a tool should render its result. | markdown |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds behavioral context: 'Amount is in currency units (negative = expense)' and lists returned fields, going beyond annotations without contradiction.
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 concise with four sentences, each carrying essential information. No unnecessary words; structured with a summary line followed by filter and return field details.
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 8 parameters, full schema coverage, annotations, and an output schema (context: true), the description adds complete context about filters, pagination, and return fields. It fully equips the agent.
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 coverage is 100%, but the description adds critical meaning: mutual exclusivity of account_id and category_id, date format for since_date, and amount semantics. This significantly enhances understanding beyond schema 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 resource (transactions of a budget) and verb (list), with specific details on filters and pagination. It distinguishes from siblings like ynab_create_transaction and ynab_update_transaction.
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 explicit guidance on filter constraints: 'Filter by account OR by category (not both), by date (since_date) and by type (uncategorized / unapproved).' It does not exclude alternatives but clearly explains when to use each filter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Partially update a transaction (categorize, approve, fix a memo…).
Only the provided fields change. Typical case: assign category_id + approved=true to an imported, uncategorized transaction.
| Name | Required | Description | Default |
|---|---|---|---|
| memo | No | New memo | |
| amount | No | New amount in currency units (negative = expense) | |
| cleared | No | 'cleared', 'uncleared' or 'reconciled' | |
| approved | No | Approve / unapprove | |
| budget_id | No | Budget id, or 'last-used' | last-used |
| payee_name | No | New payee | |
| category_id | No | New category | |
| transaction_id | Yes | Id of the transaction to edit |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate idempotent and non-destructive, and description adds partial update behavior with typical fields. No contradictions, and description adds context beyond annotations by explaining partial nature and common use.
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?
Two sentences, front-loaded with purpose, no unnecessary words. Efficient and clear.
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 8 parameters, 100% schema coverage, and existence of output schema, the description is sufficiently complete. It could mention the return value or prerequisites, but output schema covers 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 coverage is 100% with clear per-parameter descriptions. The description adds minimal extra (e.g., typical category_id+approved), but baseline 3 is appropriate since schema already does the job.
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 is to partially update a transaction, with examples like categorize, approve, fix memo. It distinguishes from sibling tools (create, list) by emphasizing the partial nature and typical use case.
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 context on when to use (partial updates) but does not explicitly exclude alternatives or mention when not to use it. The typical case is helpful but no explicit when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0ynab_create_transactionynab_get_budget_monthynab_list_accountsynab_list_budgetsynab_list_categoriesynab_list_payeesynab_list_transactionsynab_update_transactionEach tool targets a distinct operation: creating, listing, updating transactions, listing budgets, accounts, categories, payees, and retrieving budget month data. No two tools overlap in purpose.
All tool names follow the pattern `ynab_<verb>_<noun>` in snake_case, e.g., `ynab_create_transaction`, `ynab_list_accounts`. Consistent and predictable.
With 8 tools covering core CRUD and listing operations for budgets, accounts, categories, payees, and transactions, the count is well-scoped for a personal finance server.
Covers essential operations: create/update/list transactions, list budgets/accounts/categories/payees, and get budget month. Missing delete transaction is a minor gap, but typical workflows are supported.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Personal finance by conversation: expenses, receipts, statement import, budgets, net worth.
Log, query, and edit expenses, budgets, and accounts in Manilo from any MCP-compatible AI assistant.
Chat with your bank data: balances, transactions, budgets, bills. Reads only, never moves money.
Log, query, and edit expenses, budgets, and accounts in Manilo (formerly Ledgy) from any MCP-compatible AI assistant.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/chadlis/ynab-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
