make-cents-please
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., "@make-cents-please 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.
make-cents-please
A local MCP server that lets an AI assistant (such as Claude Desktop) read your budget. YNAB is the first supported platform. It also works with Charity Record donation files (see Charity Record).
Read-only by default. Every YNAB read endpoint is covered. Write tools (create, edit, delete) exist but stay switched off unless you enable them, and every write needs a preview and an explicit confirmation.
Local and single-user. It runs on your machine over stdio. There is no hosting, no multi-user support and no UI.
Your token stays local. The token is read from an environment variable and is never logged or returned in tool output.
Requirements
Python 3.11+
A YNAB account and a personal access token
Related MCP server: filesystem-mcp
Setup
Clone the repo and install dependencies:
git clone https://github.com/hopkeno/make-cents-please-MCP.git cd make-cents-please-MCP uv syncCreate a YNAB personal access token. In YNAB, go to Account Settings > Developer Settings > New Token (app.ynab.com/settings/developer). Copy it right away, because YNAB only shows it once.
Copy the example env file and add your token:
cp .env.example .env # then edit .env and set YNAB_ACCESS_TOKEN=....envis git-ignored. Never commit it.Optional check: run the tests.
uv run pytest
Configuration
Variable | Required | Default | Meaning |
| yes, unless | Your YNAB personal access token | |
| no |
| Set to |
| no |
| Plan (budget) used when a tool call has no |
| no |
| How long a cached response counts as fresh |
| no |
| Log level for stderr output |
| no |
| Set to |
| no | Folder for Charity Record CSV files; turns on the Charity Record tools (see Charity Record) |
YNAB now calls budgets "plans", and the API and SDK use that name.
Claude Desktop
Open the Claude Desktop config file:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
Add the server and use the absolute path to your clone:
{
"mcpServers": {
"make-cents-please": {
"command": "uv",
"args": [
"--directory",
"/ABSOLUTE/PATH/TO/make-cents-please-MCP",
"run",
"make-cents-please"
]
}
}
}The server reads YNAB_ACCESS_TOKEN from the .env file in the repo. You can instead put the token in an "env": { "YNAB_ACCESS_TOKEN": "..." } block in this config. That file is outside the repo, but it is stored in plain text, so protect it.
Restart Claude Desktop after editing. If Claude Desktop cannot find uv, replace "uv" with its full path (which uv on macOS/Linux, where uv on Windows).
Try asking: "What are my account balances?", "Which categories are overspent this month?" or "How much did I spend on dining out in September?"
Tools
These read tools are always available. Each takes an optional plan_id. List tools accept limit and offset and return count, total and, when more rows exist, next_offset.
Tool | What it returns | Useful filters |
| Plans with ids, currency and month range |
|
| Currency and date format | |
| Net worth, on-budget balance and entity counts, from the full plan export | |
| The token owner's user id | |
| Accounts and balances |
|
| Assigned, activity, available and goal info |
|
| Month totals (income, assigned, activity, Ready to Assign, age of money), with category detail from |
|
| Payees |
|
| GPS locations recorded by the mobile app |
|
| Transactions, newest first, with inflow/outflow/net totals for all matches |
|
| One transaction with ids and splits | |
| Upcoming and recurring transactions |
|
| Money moved between categories |
|
| Requests used this hour and cache settings, with no API call |
Output conventions and assumptions
Amounts are decimal strings in the plan's currency, such as
"-12.34", converted from YNAB's milliunits. Negative means outflow.Months accept
current,YYYY-MMorYYYY-MM-01.currentmeans the current month in UTC.Transactions default to the last 30 days when no date or month is given, to keep responses small. YNAB's own default is one year.
Hidden categories, internal categories, closed accounts, transfer payees and deleted items are left out unless you ask for them.
Results from scoped endpoints. When you filter transactions by category or payee, YNAB returns matching split lines as separate rows, linked by
parent_transaction_id.
Write tools
Write tools are only registered when YNAB_ALLOW_WRITES=true. Without it, the server cannot change your budget at all.
Tool | What it does |
| Create one or more transactions, including split transactions |
| Change fields of one transaction; omitted fields are kept |
| Change several transactions at once, e.g. approve or recategorize a batch |
| Delete a transaction |
| Import new transactions from linked accounts |
| Manage scheduled and recurring transactions |
| Set the amount assigned to a category for a month |
| Create a category, or rename, move, or set or remove its goal |
| Create or rename a category group |
| Create or rename a payee |
| Create a manual (unlinked) account with a starting balance |
How confirmation works
Every write takes two calls:
Preview. The assistant calls the tool without
confirmation_token. The server checks the input and that the ids exist, then returns a preview (for updates and deletes, the current values too) and a one-time token. Nothing is changed.Confirm. After you approve the preview, the assistant calls the same tool again with the same arguments plus the token. Only then is the request sent to YNAB.
The token is tied to the exact request that was previewed. If any argument changes, the token is refused and a new preview is needed. Each token works once and expires after 10 minutes.
What this does and does not guarantee: the server ensures that nothing is written without a preview and that what is written is exactly what was previewed. It cannot see your chat, so it relies on the assistant to show you the preview and wait for your answer, which the server's instructions and every tool description tell it to do. Claude Desktop also asks you to approve tool calls, which adds a second check; keep that approval on for write tools.
Names in the approval prompt
Claude Desktop's approval prompt shows a tool's raw arguments. So that you approve names rather than ids, every write call must include:
plan_idandplan_name. Writes never fall back to the default plan.A matching name for every other id:
account_name,category_name,category_group_nameandpayee_name.
The server checks each name against its id and refuses the call if they don't match. The check is lenient:
Case, extra spaces, emoji and other symbols are ignored.
A shortened name is accepted if it is how the real name begins and stops at the end of a word, so "Home Maintenance" matches "Home Maintenance, Repairs, Appliances, and Other House Things" but "Home Maint" does not.
The id always decides what changes; the name is there so the approval prompt is readable. Renames take the current name plus new_name.
Transactions themselves have no name, so update and delete calls still show the transaction id. Their preview shows the date, payee and amount.
Things to know
Amounts are entered in currency units, such as
-23.45. Negative means money out.Assigning money:
ynab_set_category_assignedsets the total assigned for the month; it does not add to it. To move money between categories, lower one and raise the other.Long names: YNAB allows category names of at most 50 characters, and the server applies the same limit to category group names. It appears to check the existing name on every update, so a category whose current name is longer can't be changed until it is renamed. The preview warns about this, and the error explains it.
Split transactions: their amount and categories cannot be changed through the API. Change those in the YNAB app, or delete and recreate the transaction.
After any write, the cache is cleared so the next read shows fresh data.
Network errors during a write may leave it unclear whether the change was applied. The error says so; check the data before trying again.
Using with YNAB's own MCP server
YNAB offers its own hosted MCP server (see YNAB's MCP Server). It covers the everyday YNAB reads and writes, uses OAuth instead of a token, and works in Claude on the web and mobile and in ChatGPT.
If you use it for YNAB, set YNAB_TOOLS=off here. Two sets of near-identical YNAB tools in one client make the assistant choose between them inconsistently. With YNAB tools off:
Hidden: all
ynab_*tools.YNAB_ALLOW_WRITEShas no effect.Still available: the Charity Record tools.
With a
YNAB_ACCESS_TOKEN:charityrecord_find_ynab_donationsandcharityrecord_reconcilekeep working, because they read YNAB directly.Without a token: those two tools are left out, and the token isn't required.
Things this server can do that YNAB's own server doesn't list (as of November 2026): delete transactions and scheduled transactions, bulk-edit transactions, import from linked accounts, assign money in months other than the current one, create or rename payees, and create accounts. Turn YNAB_TOOLS back on if you need them.
Charity Record
Charity Record tracks charitable donations for taxes. It has no API, only CSV import and export, so these tools work with files in a folder you choose (CHARITYRECORD_DIR). Nothing is sent to Charity Record directly.
Reading: in Charity Record, use Download data to export a year's CSVs into the folder. Subfolders one level deep are fine, so you can unzip a "Download All" file there.
Writing: the assistant writes new import files into the folder. You upload them on Charity Record's import page and check its import preview before importing.
Tool | What it does |
| List CSV files in the folder with their detected type, years and donation counts |
| List exported donations, filtered by year, charity, type or dates, with totals |
| Totals by year, by donation type and by charity |
| Find donations in YNAB by category or payee and shape them as cash donations |
| Compare YNAB donations with your exports: missing in Charity Record, only in Charity Record, and amount mismatches |
| Write import CSVs, one per donation type, from donations you describe or that came from YNAB |
Things to know:
Donation types: import files can hold any of Charity Record's types (items, cash, mileage, stock, vehicle, digital asset and art), in the column layout from Charity Record's Import Format Guide. You can describe donations in plain language, for example "I drove 26 miles from home to the shelter for Charity X on October 12" or "here's what I gave the thrift store on October 20".
Mileage is recorded as miles, the rate per mile and the dollar value. The rate defaults to 14 cents per mile, the charitable rate set by law (26 U.S.C. 170(i)), and can be overridden.
Values are the ones you give. The assistant must not estimate fair market values.
Confirmation: writing import files uses the same preview and one-time confirmation as other writes. It only writes local files, so it doesn't need
YNAB_ALLOW_WRITES.Duplicates: donations that already appear in your exports (same type, charity, date and value) are left out by default. Charity Record adds imported rows rather than replacing them, so a duplicate would be recorded twice.
Never overwritten: generated files are named
charityrecord-import-<date-time>-<type>.csv, and existing files are never overwritten.Export format: Charity Record doesn't document its export columns. The reader was checked against a real 2026 export:
Every file matches the import layouts.
The cash file spells one column "Addtional Payment Details". Both spellings are accepted when reading, and import files use the export's spelling.
The Overall summary uses the types "Item" and "Money".
If a file isn't recognized,
charityrecord_list_filesshows the headers it found.
Recurring donations are exported with the date "Various" and a times-per-year frequency. They are listed with their tax year, taken from the export's file name (for example
CharityRecord_2026_cash_....csv), and left out of date-range filters. Reconcile reports a YNAB payment to a charity with a recurring entry as "possibly covered by recurring" rather than missing. The value Charity Record exports for a recurring donation is used as is, and it matches the Overall summary.
Rate limits and caching
YNAB allows 200 requests per hour per token. To stay under that limit:
In-memory cache. Responses are kept in memory only and never written to disk, so the cache resets when the server restarts. Repeat questions within
YNAB_CACHE_TTL_SECONDSmake no requests.Delta requests. When cached data goes stale, it is refreshed with a delta request (
last_knowledge_of_server) wherever YNAB supports one: the plan export, accounts, categories, months, payees, transactions and scheduled transactions. The changes are merged into the cache.Request tracking. The server counts requests in a sliding one-hour window and also reads YNAB's
X-Rate-Limitheader.Near the limit. Above 180 requests in the window, cached data is served with a
warningsaying it may be out of date.At the limit, or after a 429 response. Cached data is served if there is any. Otherwise the tool returns an error saying roughly how long to wait.
Errors
Errors are short and tell the model what to do next. For example, a 404 says to look up valid ids with the matching list_* tool, a 401 says to replace the token, and a 5xx says to retry later. Malformed ids and dates are rejected before any request is sent.
Safety
The token comes only from the environment or
.env. It is never logged, echoed or included in errors. Logs go to stderr, because stdout carries the MCP protocol, and a redaction filter strips the token and anyBearer ...value.Fixtures.
.envis git-ignored. Test fixtures are synthetic: no real budget data, names or ids.Writes. Write tools are off unless
YNAB_ALLOW_WRITES=true, and every write needs a preview and a matching one-time confirmation token. See How confirmation works.
Development
uv run pytest # tests run against mocked YNAB HTTP responses; no token or network needed
uv run ruff check .
uv run ruff format .Layout:
src/make_cents_please/
__main__.py entry point (stdio)
server.py builds the MCP server
config.py env config; token wrapped so it never prints
logging_setup.py stderr logging with redaction
providers/ynab/
client.py SDK wrapper: rate tracking, caching, error mapping
cache.py in-memory TTL cache and delta merge
formatting.py compact rows, amounts, dates, pagination
tools.py read tool definitions
write_tools.py write tool definitions (only with YNAB_ALLOW_WRITES=true)
confirm.py preview and one-time confirmation tokens
providers/charityrecord/
formats.py CSV layouts, donation models, writer and export reader
files.py folder-restricted file access, no overwrites
tools.py Charity Record tool definitions (only with CHARITYRECORD_DIR)
tests/ pytest suite with a fake YNAB HTTP layer (tests/fakes.py)Support for other platforms goes in a new folder under providers/.
GitHub Actions runs the same lint, format and test checks on every pull request and on pushes to main, on Python 3.11, 3.12 and 3.13 (.github/workflows/ci.yml).
Contributing
This repository is published from a private development repository at each release. See CHANGELOG.md for what changed. Issues are welcome. Pull requests are welcome too, but accepted changes are applied in the development repository and arrive here with the next release rather than being merged directly.
License
MIT. See LICENSE.
Available Tools
21 toolsynab_get_accountBRead-only
Get one account's details and balances.
Inputs: account_id (required), plan_id. Returns: object
ynab_get_api_statusARead-only
Show how many of the 200 hourly YNAB API requests have been used and cache settings. Makes no API call.
Inputs: no named parameters. Returns: object
ynab_get_categoryBRead-only
Get one category's assigned, activity, available and goal details, optionally for a specific month.
Inputs: category_id (required), month, plan_id. Returns: object
ynab_get_monthBRead-only
Get one budget month: totals (income, assigned, activity, Ready to Assign, age of money) plus per-category assigned/activity/available for that month.
Inputs: group, month, plan_id, include_zero, +2 more. Returns: object
ynab_get_payeeCRead-only
Get one payee.
Inputs: payee_id (required), plan_id. Returns: object
ynab_get_payee_locationCRead-only
Get one payee location.
Inputs: payee_location_id (required), plan_id. Returns: object
ynab_get_plan_overviewARead-only
Summarize a whole plan: account balances, net worth and how many categories, payees and transactions it has. Uses YNAB's full plan export (refreshed by delta), but returns only totals and counts. For details use the list_* tools.
Inputs: plan_id. Returns: object
ynab_get_plan_settingsARead-only
Get a plan's currency and date format settings.
Inputs: plan_id. Returns: object
ynab_get_scheduled_transactionCRead-only
Get one scheduled transaction.
Inputs: scheduled_transaction_id (required), plan_id. Returns: object
ynab_get_transactionARead-only
Get one transaction in full, including ids, import details and splits.
Inputs: transaction_id (required), plan_id. Returns: object
ynab_get_userARead-only
Get the id of the YNAB user that owns the access token. Rarely needed.
Inputs: no named parameters. Returns: object
ynab_list_accountsARead-only
List accounts with current, cleared and uncleared balances. Use this to find account_id values for other tools.
Inputs: limit, offset, plan_id, on_budget, +2 more. Returns: object
ynab_list_categoriesARead-only
List budget categories with assigned (budgeted), activity and available (balance) amounts and goal info. Use this to find category_id values and to check spending against the budget.
Inputs: group, limit, month, offset, +5 more. Returns: object
ynab_list_money_movement_groupsARead-only
List groups of money movements (one group per assign/move action), newest first.
Inputs: limit, month, offset, plan_id. Returns: object
ynab_list_money_movementsARead-only
List money moved between categories (assigning or reassigning funds), newest first, with category names.
Inputs: limit, month, offset, plan_id. Returns: object
ynab_list_monthsARead-only
List budget months (newest first) with income, assigned, activity, Ready to Assign and age of money. Good for month-over-month trends.
Inputs: limit, offset, plan_id, since_month, +1 more. Returns: object
ynab_list_payee_locationsBRead-only
List GPS locations recorded for payees by the YNAB mobile app.
Inputs: limit, offset, plan_id, payee_id. Returns: object
ynab_list_payeesARead-only
List payees (merchants, people, transfer targets). Use this to find payee_id values.
Inputs: limit, offset, plan_id, name_contains, +1 more. Returns: object
ynab_list_plansARead-only
List the user's YNAB plans (budgets) with ids, currency and month range.
Call this first if you need a plan_id; most tools default to the configured plan.
Inputs: include_accounts. Returns: object
ynab_list_scheduled_transactionsBRead-only
List scheduled (recurring or future) transactions, soonest first. Useful for upcoming bills.
Inputs: limit, offset, plan_id, account_id, +2 more. Returns: object
ynab_list_transactionsARead-only
Search transactions (newest first) with filters for dates, account, category, payee, amount and text. Returns a page of compact rows plus inflow/outflow totals for all matches. Split transactions show their splits; when filtering by category or payee, matching split lines are returned individually.
Inputs: text, limit, month, offset, +11 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 21 tools
The get/list pairing per resource is clear, and descriptions explicitly delineate similar pairs (e.g. list_money_movements vs. list_money_movement_groups, get_plan_settings vs. get_plan_overview). Minor overlap remains: get_month returns per-category data that get_category can also return for a given month, and get_plan_overview partly duplicates what list_* tools provide, but the descriptions steer the agent adequately.
Every tool follows the same ynab_verb_noun pattern (ynab_list_accounts, ynab_get_transaction, ynab_get_api_status), with consistent snake_case throughout. There are no naming deviations or mixed conventions.
At 21 tools this sits in the heavy range for what is essentially a read-only budget reader, and several earn little: ynab_get_user is self-described as 'rarely needed', and the payee-location pair and ynab_get_api_status are marginal. The core resource get/list pairs are justified, but the surface could be trimmed to ~15 without loss.
The read surface is thorough — plans, accounts, categories, months, payees, locations, transactions, scheduled transactions, money movements and plan overview are all covered. However there are zero write operations (no creating/updating transactions, assigning funds, or mutating categories), which is a notable gap for a budgeting domain that the YNAB API supports.
Maintenance
Related MCP Connectors
Safe folder access for ChatGPT and Claude: read, write and search files, risky tools opt-in.
Read your accounts, budgets and net worth, and draft changes you confirm.
Ask your AI about your own accounts, debts, budgets and goals. OAuth sign-in, read-only by default.
Read-only access to your own bank, card and brokerage accounts for Claude, ChatGPT and other AI agents: balances, transactions, spending, subscriptions, cashflow and investment holdings. It can never move money.
Related MCP Servers
- AlicenseBqualityAmaintenanceEnables AI assistants to interact with YNAB budgets, performing read-only queries by default and optional write operations like creating transactions and managing categories through natural language.45950 npm53MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to read, write, and manage files on the local system with security features like path restrictions and optional read-only mode.92MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to securely read and analyze local files such as CSV, JSON, and PDF from the project directory, allowing tasks like spending analysis.ISC
- AlicenseAqualityCmaintenanceProvides a read-only interface to YNAB budget data, allowing AI assistants to inspect budgets, accounts, categories, transactions, and more. Includes an experimental guarded write workflow for category assignments.108 npmMIT