py-ynab-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| YNAB_ACCESS_TOKEN | Yes | Your YNAB Personal Access Token from https://app.ynab.com/settings/developer |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
| experimental | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| list_budgetsA | List all budgets for the authenticated YNAB user. Returns budget names, IDs, date ranges, and last modified dates. Use the budget ID with other tools to target a specific budget. |
| list_accountsA | List all accounts for a YNAB budget with balances. Args: budget_id: Budget ID to list accounts for. If not provided, uses the default budget. |
| list_categoriesA | List all categories for a YNAB budget, grouped by category group. Returns category names and IDs needed for creating transactions. Args: budget_id: Budget ID to list categories for. If not provided, uses the default budget. |
| list_payeesA | List all payees for a YNAB budget. Returns payee names and IDs. Args: budget_id: Budget ID to list payees for. If not provided, uses the default budget. |
| list_monthsA | List all budget months with summary figures. Returns each month's income, budgeted, activity, available (to-be-budgeted), and age of money. Args: budget_id: Budget ID. If not provided, uses the default budget. |
| get_monthA | Get a single budget month with per-category breakdown. Returns the month summary (income, budgeted, activity, available) plus every category's budgeted/activity/balance. Args: month: Month to retrieve (YYYY-MM-DD, first of month, e.g. "2026-03-01") or "current" for the current month. budget_id: Budget ID. Defaults to last-used budget. |
| list_transactionsA | List transactions from YNAB with optional filters. Returns transactions since the given date. Optionally filter by one of: account, category, or payee (mutually exclusive). Args: since_date: Start date (YYYY-MM-DD). Required. account_id: Filter by account UUID. category_id: Filter by category UUID. payee_id: Filter by payee UUID. type: Filter by "uncategorized" or "unapproved". budget_id: Budget ID. Defaults to last-used budget. |
| create_transactionA | Create a transaction in YNAB. Args: account_id: Account UUID. amount: Dollar amount ("-42.50" for outflow, "100.00" for inflow). date: Transaction date (YYYY-MM-DD). payee_name: Payee name (YNAB auto-creates new payees). payee_id: Payee UUID, including an account transfer payee ID. category_id: Category UUID. Omit when splitting. memo: Transaction memo. cleared: "cleared", "uncleared", or "reconciled". approved: Whether the transaction is approved. subtransactions_json: JSON array of split legs, to record one card charge against several categories. Each element: {"amount", "category_id"?, "payee_name"?, "payee_id"?, "memo"?}. Amounts are dollars with the same sign as the parent (e.g. "-30.00") and must sum to it. Needs at least two legs, and category_id must be left off the parent. budget_id: Budget ID. Defaults to last-used budget. dry_run: Validate and preview without creating. |
| create_transactionsA | Create multiple transactions in YNAB in a single API call. Preferred over create_transaction when creating multiple transactions to minimize rate limit usage. Args: transactions_json: JSON array of transactions. Each element: {"account_id", "amount", "date", "payee_name"?, "payee_id"?, "category_id"?, "memo"?, "cleared"?, "approved"?}. Amounts are in dollars (e.g. "-42.50"). budget_id: Budget ID. Defaults to last-used budget. dry_run: Validate and preview without creating. |
| update_transactionA | Update fields of an existing YNAB transaction. Only provide the fields you want to change. Args: transaction_id: Transaction UUID to update. account_id: New account UUID. amount: New dollar amount ("-42.50" for outflow). date: New date (YYYY-MM-DD). payee_name: New payee name. payee_id: New payee UUID, including an account transfer payee ID. category_id: New category UUID. Omit when splitting. memo: New memo. cleared: "cleared", "uncleared", or "reconciled". approved: Whether the transaction is approved. subtransactions_json: JSON array of split legs, converting this into a split transaction. Each element: {"amount", "category_id"?, "payee_name"?, "payee_id"?, "memo"?}. Amounts are dollars with the same sign as the parent and must sum to it. Pass amount too, so the legs can be checked against the total. Replaces any existing legs. budget_id: Budget ID. Defaults to last-used budget. dry_run: Validate and preview without updating. |
| delete_transactionB | Delete a transaction from YNAB. Args: transaction_id: Transaction UUID to delete. budget_id: Budget ID. Defaults to last-used budget. dry_run: Validate and preview without deleting. |
| update_category_budgetA | Set the budgeted (assigned) amount for a category in a specific month. Args: category_id: Category UUID. month: Month to update (YYYY-MM-DD, first of month, e.g. "2026-03-01"). amount: Dollar amount to assign (e.g. "500.00"). budget_id: Budget ID. Defaults to last-used budget. dry_run: Validate and preview without updating. |
| create_categoryA | Create a category in a YNAB category group. Args: category_group_id: Category group UUID. name: Category name. note: Optional category note. target_amount: Optional positive target amount in dollars. target_date: Optional target date in YYYY-MM-DD format. target_needs_whole_amount: Whether the entire target is needed. target_frequency: Optional target recurrence: monthly, weekly, or yearly. Cannot be combined with target_date. budget_id: Budget ID. Defaults to last-used budget. dry_run: Validate and preview without creating. |
| update_categoryA | Update category metadata or target configuration in YNAB. Only provide the fields you want to change. Args: category_id: Category UUID. name: New category name. note: New category note. category_group_id: New category group UUID. target_amount: Positive target amount in dollars. target_date: Target date in YYYY-MM-DD format. target_needs_whole_amount: Whether the entire target is needed. target_frequency: Target recurrence: monthly, weekly, or yearly. Cannot be combined with target_date. budget_id: Budget ID. Defaults to last-used budget. dry_run: Validate and preview without updating. |
| clear_category_targetA | Remove a category target without changing its assigned money. Args: category_id: Category UUID. budget_id: Budget ID. Defaults to last-used budget. dry_run: Validate and preview without clearing the target. |
| list_scheduled_transactionsB | List all scheduled transactions for a YNAB budget. Returns each scheduled transaction with its frequency, next date, amount, payee, and category. Args: budget_id: Budget ID. If not provided, uses the default budget. |
| get_scheduled_transactionA | Get details of a single scheduled transaction. Returns full detail including subtransactions if present. Args: scheduled_transaction_id: Scheduled transaction UUID. budget_id: Budget ID. Defaults to last-used budget. |
| create_scheduled_transactionA | Create a scheduled (recurring) transaction in YNAB. Args: account_id: Account UUID. amount: Dollar amount ("-42.50" for outflow, "100.00" for inflow). date: First occurrence date (YYYY-MM-DD). frequency: Recurrence frequency. Only single-word values work via the YNAB API: "never", "daily", "weekly", "monthly", "yearly". Multi-word camelCase values (everyOtherWeek, twiceAMonth, etc.) are documented but rejected by YNAB's own backend — set those manually in the YNAB UI. payee_name: Payee name. category_id: Category UUID. memo: Transaction memo. flag_color: Flag color. budget_id: Budget ID. Defaults to last-used budget. dry_run: Validate and preview without creating. |
| update_scheduled_transactionA | Update fields of an existing scheduled transaction. Only provide the fields you want to change. Args: scheduled_transaction_id: Scheduled transaction UUID. account_id: New account UUID. amount: New dollar amount. date: New first date (YYYY-MM-DD). frequency: New frequency. Only single-word values work via the YNAB API: "never", "daily", "weekly", "monthly", "yearly". Multi-word values are rejected by YNAB's backend — change those in the UI. payee_name: New payee name. category_id: New category UUID. memo: New memo. flag_color: New flag color. budget_id: Budget ID. Defaults to last-used budget. dry_run: Validate and preview without updating. |
| delete_scheduled_transactionA | Delete a scheduled transaction from YNAB. Args: scheduled_transaction_id: Scheduled transaction UUID. budget_id: Budget ID. Defaults to last-used budget. dry_run: Validate and preview without deleting. |
| get_userA | Get the authenticated YNAB user. Returns the user ID. |
| get_budget_settingsA | Get budget settings including date and currency format. Args: budget_id: Budget ID. Defaults to last-used budget. |
| get_accountA | Get a single YNAB account with full details. Returns balance, type, on-budget status, note, and more. Args: account_id: Account UUID. budget_id: Budget ID. Defaults to last-used budget. |
| get_categoryA | Get a single YNAB category with budget details. Returns budgeted, activity, balance, and metadata. Args: category_id: Category UUID. budget_id: Budget ID. Defaults to last-used budget. |
| get_payeeC | Get a single YNAB payee. Args: payee_id: Payee UUID. budget_id: Budget ID. Defaults to last-used budget. |
| update_payeeA | Update a YNAB payee (rename). Args: payee_id: Payee UUID. name: New name for the payee. budget_id: Budget ID. Defaults to last-used budget. dry_run: Validate and preview without updating. |
| get_transactionB | Get a single YNAB transaction with full details. Args: transaction_id: Transaction UUID. budget_id: Budget ID. Defaults to last-used budget. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 27 tools
Most tools target a distinct resource and action, and singular/plural pairs like get_transaction vs list_transactions are predictable. The only real ambiguity is create_transaction vs create_transactions, but the description explicitly guides users to the plural version for batch creation.
All tool names consistently follow snake_case verb_noun patterns: list_*, get_*, create_*, update_*, delete_*. Plural nouns are used only for list operations, and verb choice is uniform across resources.
27 tools is heavy, but it reflects the wide YNAB domain: transactions, scheduled transactions, categories, payees, accounts, budgets, and months. Each tool has a clear role, though the set is large enough to add navigation overhead.
Transactions and scheduled transactions have full CRUD coverage, and categories/payees/accounts have solid read and write operations. Minor gaps like no account creation or category deletion exist, but the main YNAB budgeting workflows are covered without dead ends.