A
licenseA
qualityB
maintenanceAn MCP server that allows users to interact with YNAB data, enabling access to account balances, transactions, and the creation of new transactions through the Model Context Protocol.
8
6
MIT
mcp-ynab
by alexfu
This MCP server exposes the YNAB API, letting MCP clients read and modify YNAB budget data using a YNAB personal access token.
Get authenticated user information.
List plans and retrieve plan details/settings.
Manage accounts: list, get, and create.
Manage categories and category groups: list, get, create/update categories, get/update monthly category budgeted amounts, and create/update category groups.
Manage payees and payee locations: list, get, create/update payees, and list/get payee locations.
View plan months and month details.
View money movements and money movement groups, including by month.
Manage transactions: list/filter by account, category, payee, or month; get; create single or bulk; update single or bulk; delete; and import linked-account transactions.
Manage scheduled transactions: list, get, create, update, and delete.
Authenticate via per-request Bearer token in HTTP mode, or
YNAB_TOKENin stdio mode.
Click on "Deploy 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., "@mcp-ynab show me my budget categories"
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.
mcp-ynab
FastMCP server that exposes the YNAB API via MCP using YNAB's published OpenAPI spec.
Requirements
Python 3.12+
A YNAB personal access token
uv(recommended) orpip
Related MCP server: ynab-mcp
Configuration
Environment variables:
TRANSPORT(optional):http(default) orstdioYNAB_TOKEN(required instdiomode only): your YNAB API token
Authentication
How the server authenticates with YNAB depends on the transport:
HTTP: the server holds no token. Each MCP client sends its own YNAB token with every request, and the server forwards it to YNAB:
Authorization: Bearer <YNAB personal access token>Requests without this header fail with a "Missing Authorization header" error.
stdio: there are no request headers, so the server reads a single token from
YNAB_TOKENat startup.
Run Locally
Using uv:
uv sync
export TRANSPORT="http" # optional, defaults to http
uv run python main.pyHTTP mode starts the server on 0.0.0.0:8080, with the MCP endpoint at /mcp.
For stdio mode:
export YNAB_TOKEN="your_token_here"
export TRANSPORT="stdio"
uv run python main.pyDocker
Use the prebuilt image from GHCR:
docker pull ghcr.io/alexfu/mcp-ynab:latestRun prebuilt image in HTTP mode:
docker run --rm -p 8080:8080 \
-e TRANSPORT="http" \
ghcr.io/alexfu/mcp-ynab:latestRun prebuilt image in stdio mode:
docker run --rm -i \
-e YNAB_TOKEN="your_token_here" \
-e TRANSPORT="stdio" \
ghcr.io/alexfu/mcp-ynab:latestConnecting a Client
Claude (custom connector)
In Claude, add a custom connector:
Set the URL to
https://<your-host>/mcp.Under Authentication, choose No sign-in.
Under Request headers, add
authorizationwith the valueBearer <your YNAB token>.
Claude Code
claude mcp add --transport http ynab https://<your-host>/mcp \
--header "Authorization: Bearer <your YNAB token>"Notes
The server fetches YNAB's OpenAPI spec at startup from
https://api.ynab.com/papi/open_api_spec.yaml.Startup will fail if
TRANSPORTis invalid,YNAB_TOKENis missing in stdio mode, or the spec request fails.Serve HTTP mode over HTTPS when it's reachable outside your machine, since every request carries a YNAB token.
Available Tools
44 toolscreateAccountD
Creates a new account
Inputs: account (required), plan_id (required). Returns: data
createCategoryB
Creates a new category
Inputs: plan_id (required), category (required). Returns: data
createCategoryGroupC
Creates a new category group
Inputs: plan_id (required), category_group (required). Returns: data
createPayeeC
Creates a new payee
Inputs: payee (required), plan_id (required). Returns: data
createScheduledTransactionC
Creates a single scheduled transaction (a transaction with a future date).
Inputs: plan_id (required), scheduled_transaction (required). Returns: data
createTransactionA
Creates a single transaction or multiple transactions. If you provide a body containing a transaction object, a single transaction will be created and if you provide a body containing a transactions array, multiple transactions will be created. Scheduled transactions (transactions with a future date) cannot be created on this endpoint.
Inputs: plan_id (required), transaction, transactions. Returns: data
deleteScheduledTransactionB
Deletes a scheduled transaction
Inputs: plan_id (required), scheduled_transaction_id (required). Returns: data
deleteTransactionC
Deletes a transaction
Inputs: plan_id (required), transaction_id (required). Returns: data
getAccountByIdB
Returns a single account
Inputs: plan_id (required), account_id (required). Returns: data
getAccountsC
Returns all accounts
Inputs: plan_id (required), last_knowledge_of_server. Returns: data
getCategoriesA
Returns all categories grouped by category group. Amounts (assigned, activity, available, etc.) are specific to the current plan month (UTC).
Inputs: plan_id (required), last_knowledge_of_server. Returns: data
getCategoryByIdA
Returns a single category. Amounts (assigned, activity, available, etc.) are specific to the current plan month (UTC).
Inputs: plan_id (required), category_id (required). Returns: data
getMoneyMovementGroupsC
Returns all money movement groups
Inputs: plan_id (required). Returns: data
getMoneyMovementGroupsByMonthB
Returns all money movement groups for a specific month
Inputs: month (required), plan_id (required). Returns: data
getMoneyMovementsC
Returns all money movements
Inputs: plan_id (required). Returns: data
getMoneyMovementsByMonthA
Returns all money movements for a specific month
Inputs: month (required), plan_id (required). Returns: data
getMonthCategoryByIdA
Returns a single category for a specific plan month. Amounts (assigned, activity, available, etc.) are specific to the current plan month (UTC).
Inputs: month (required), plan_id (required), category_id (required). Returns: data
getPayeeByIdB
Returns a single payee
Inputs: plan_id (required), payee_id (required). Returns: data
getPayeeLocationByIdC
Returns a single payee location
Inputs: plan_id (required), payee_location_id (required). Returns: data
getPayeeLocationsB
Returns all payee locations
Inputs: plan_id (required). Returns: data
getPayeeLocationsByPayeeB
Returns all payee locations for a specified payee
Inputs: plan_id (required), payee_id (required). Returns: data
getPayeesB
Returns all payees
Inputs: plan_id (required), last_knowledge_of_server. Returns: data
getPlanByIdA
Returns a single plan with all related entities. This resource is effectively a full plan export.
Inputs: plan_id (required), last_knowledge_of_server. Returns: data
getPlanMonthA
Returns a single plan month
Inputs: month (required), plan_id (required). Returns: data
getPlanMonthsC
Returns all plan months
Inputs: plan_id (required), last_knowledge_of_server. Returns: data
getPlansB
Returns plans list with summary information
Inputs: include_accounts. Returns: data
getPlanSettingsByIdB
Returns settings for a plan
Inputs: plan_id (required). Returns: data
getScheduledTransactionByIdA
Returns a single scheduled transaction
Inputs: plan_id (required), scheduled_transaction_id (required). Returns: data
getScheduledTransactionsC
Returns all scheduled transactions
Inputs: plan_id (required), last_knowledge_of_server. Returns: data
getTransactionByIdC
Returns a single transaction
Inputs: plan_id (required), transaction_id (required). Returns: data
getTransactionsB
Returns plan transactions, excluding any pending transactions
Inputs: plan_id (required), type, since_date, until_date, +1 more. Returns: data
getTransactionsByAccountA
Returns all transactions for a specified account, excluding any pending transactions
Inputs: plan_id (required), account_id (required), type, since_date, +2 more. Returns: data
getTransactionsByCategoryA
Returns all transactions for a specified category, excluding any pending transactions
Inputs: plan_id (required), category_id (required), type, since_date, +2 more. Returns: data
getTransactionsByMonthA
Returns all transactions for a specified month, excluding any pending transactions
Inputs: month (required), plan_id (required), type, since_date, +2 more. Returns: data
getTransactionsByPayeeB
Returns all transactions for a specified payee, excluding any pending transactions
Inputs: plan_id (required), payee_id (required), type, since_date, +2 more. Returns: data
getUserB
Returns authenticated user information
Inputs: no named parameters. Returns: data
importTransactionsA
Imports available transactions on all linked accounts for the given plan. Linked accounts allow transactions to be imported directly from a specified financial institution and this endpoint initiates that import. Sending a request to this endpoint is the equivalent of clicking "Import" on each account in the web application or tapping the "New Transactions" banner in the mobile applications. The response for this endpoint contains the transaction ids that have been imported.
Inputs: plan_id (required). Returns: data
updateCategoryC
Update a category
Inputs: plan_id (required), category (required), category_id (required). Returns: data
updateCategoryGroupC
Update a category group
Inputs: plan_id (required), category_group (required), category_group_id (required). Returns: data
updateMonthCategoryA
Update a category for a specific month. Only budgeted (assigned) amount can be updated.
Inputs: month (required), plan_id (required), category (required), category_id (required). Returns: data
updatePayeeD
Update a payee
Inputs: payee (required), plan_id (required), payee_id (required). Returns: data
updateScheduledTransactionC
Updates a single scheduled transaction
Inputs: plan_id (required), scheduled_transaction (required), scheduled_transaction_id (required). Returns: data
updateTransactionC
Updates a single transaction
Inputs: plan_id (required), transaction (required), transaction_id (required). Returns: data
updateTransactionsB
Updates multiple transactions, by id or import_id.
Inputs: plan_id (required), transactions (required). Returns: data
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
C2.8/5.0
Scored across 44 tools
Disambiguation5/5
Each tool targets a distinct resource and action. Get, create, update, and delete operations are clearly separated per entity, and even similar tools like getCategoryById vs getMonthCategoryById are differentiated by their descriptions (month-specific vs current month). No two tools appear to do the same thing.
Naming Consistency4/5
All tools follow a verb_noun camelCase pattern (getPlans, createAccount, updateTransaction). Minor deviations exist such as getPlanMonth vs getPlanMonths and some singular/plural inconsistencies, but the pattern is recognizable and predictable.
Tool Count2/5
With 44 tools, this is far beyond the typical MCP server scope and feels bloated. While the domain (YNAB budgeting) is complex, the number of tools is excessive and would likely overwhelm an agent, making selection harder.
Completeness3/5
The tool surface covers transactions and categories thoroughly with full CRUD, but gaps exist: accounts lack update/delete, plans have no create/update, payee locations are read-only, and money movements have no write operations. These missing operations could hinder common budgeting workflows.
Maintenance
ActivityMaintained
ResponsivenessOutdated data
Related MCP Connectors
Hosted remote MCP server for YNAB on Cloudflare Workers with OAuth
Query your real net worth, spending, transactions, budgets and portfolio from any MCP client.
MCP server for the Seline Analytics API
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol (MCP) server for interacting with YNAB (You Need A Budget). Provides tools for accessing budget data through MCP-enabled clients like Claude Desktop.4MIT
- AlicenseNot gradedqualityCmaintenanceRead-only MCP server for YNAB that provides tools for budgets, accounts, categories, transactions, and financial summaries via HTTP or stdio.1MIT
- AlicenseAqualityAmaintenanceA Model Context Protocol server for YNAB (You Need A Budget). Enables users to query budgets, accounts, categories, transactions, and more, as well as create, update, and delete transactions and manage scheduled transactions from any MCP client.2718 PyPI2MIT