ynab-mcp
ynab-mcp
전체 YNAB API를 노출하는 MCP(Model Context Protocol) 서버로, LLM이 자연어를 통해 예산을 읽고 관리할 수 있게 합니다. CRUD 작업을 위한 도구, 주변 예산 컨텍스트를 위한 리소스, 그리고 가이드가 포함된 재무 워크플로우를 위한 프롬프트를 제공합니다.
요구 사항
Node.js 20+
Related MCP server: YNAB MCP Server
설치
npm install -g ynab-mcp또는 소스에서 설치:
git clone https://github.com/justmytwospence/ynab-mcp.git
cd ynab-mcp
npm install
npm run build
npm install -g .구성
YNAB API 토큰을 환경 변수로 설정하세요:
export YNAB_API_TOKEN="your-token-here"YNAB > 계정 설정 > 개발자 설정에서 토큰을 생성하세요.
Claude Code
claude mcp add ynab-mcp ynab-mcp -e YNAB_API_TOKEN=your-token-hereClaude Desktop
claude_desktop_config.json에 추가하세요:
{
"mcpServers": {
"ynab-mcp": {
"command": "ynab-mcp",
"env": {
"YNAB_API_TOKEN": "your-token-here"
}
}
}
}도구
전체 YNAB API를 다루는 50개의 도구입니다. 모든 금액은 YNAB의 밀리유닛(milliunits) 형식을 사용합니다 (예: $12.34 = 12340).
사용량 제한(Rate limit) 안내
YNAB API는 토큰당 시간당 200회 요청(슬라이딩 윈도우)으로 사용량을 제한합니다. 서버는 모든 호출을 추적하며 다음을 제공합니다:
get_api_usage도구 /ynab://api-usage리소스 — 명시적, 온디맨드 확인 (API 호출 0회).사용량이 많아지면 모든 도구 결과에 자동 경고가 추가됩니다:
남은 횟수가 50회 이하일 때
[RATE LIMIT WARNING]남은 횟수가 20회 이하일 때
[RATE LIMIT CRITICAL]남은 횟수가 0회일 때
[RATE LIMIT REACHED]
각 도구의 설명에는 괄호 안에 API 호출 비용이 포함되어 있습니다 (예: [1 API call]). 단일 호출 도구를 반복하는 것보다 일괄 처리 도구(create_transactions, update_transactions)를 사용하는 것을 권장합니다.
사용자
도구 | 설명 |
| 인증된 사용자 정보 가져오기 |
예산
도구 | 설명 |
| 선택적 계좌 정보를 포함하여 모든 예산 나열 |
| 모든 엔티티를 포함한 예산의 전체 세부 정보 가져오기 |
| 날짜 및 통화 형식 설정 가져오기 |
계좌
도구 | 설명 |
| 잔액 및 유형을 포함한 모든 계좌 나열 |
| 단일 계좌의 세부 정보 가져오기 |
| 새 계좌 생성 |
카테고리
도구 | 설명 |
| 카테고리 그룹별로 모든 카테고리 나열 |
| 단일 카테고리의 세부 정보 가져오기 |
| 새 카테고리 생성 |
| 카테고리 이름, 메모 또는 목표 업데이트 |
| 특정 월의 카테고리 예산 가져오기 |
| 특정 월의 카테고리 예산 금액 업데이트 |
| 새 카테고리 그룹 생성 |
| 카테고리 그룹 이름 업데이트 |
거래
도구 | 설명 |
| 선택적 필터를 사용하여 거래 나열 |
| 단일 거래의 세부 정보 가져오기 |
| 새 거래 생성 |
| 여러 거래 일괄 생성 |
| 기존 거래 업데이트 |
| 여러 거래 일괄 업데이트 |
| 거래 삭제 |
| 연결된 금융 기관에서 가져오기 |
| 특정 계좌의 거래 나열 |
| 특정 카테고리의 거래 나열 |
| 특정 수취인의 거래 나열 |
| 특정 월의 거래 나열 |
예약된 거래
도구 | 설명 |
| 모든 예약/반복 거래 나열 |
| 예약된 거래의 세부 정보 가져오기 |
| 새 예약 거래 생성 |
| 예약된 거래 업데이트 |
| 예약된 거래 삭제 |
수취인
도구 | 설명 |
| 모든 수취인 나열 |
| 단일 수취인의 세부 정보 가져오기 |
| 수취인 이름 업데이트 |
수취인 위치
도구 | 설명 |
| 모든 수취인 GPS 위치 나열 |
| 단일 수취인 위치 가져오기 |
| 특정 수취인의 모든 위치 가져오기 |
월
도구 | 설명 |
| 요약과 함께 모든 예산 월 나열 |
| 카테고리 잔액을 포함한 상세 월 정보 가져오기 |
자금 이동
도구 | 설명 |
| 모든 자금 이동 나열 |
| 특정 월의 자금 이동 가져오기 |
| 모든 자금 이동 그룹 나열 |
| 특정 월의 자금 이동 그룹 가져오기 |
워크플로우
도구 | 설명 |
| 소스 카테고리를 대상 카테고리로 병합하여 모든 거래 및 예산 금액 이동 |
| 삭제를 위해 카테고리 정리: 모든 기록을 대체 카테고리로 재분류하고 예산을 0으로 설정 (최종 삭제는 YNAB 앱에서 수동으로 수행 - API 제한) |
| 카드 잔액 대비 신용카드 결제 카테고리 잔액 감사 (자동 수정 옵션 포함) |
리소스
리소스는 클라이언트가 도구 호출 없이 컨텍스트로 가져올 수 있는 구조화된 예산 데이터를 제공합니다. 템플릿 리소스는 URI 매개변수(예: {budget_id})를 사용합니다.
리소스 | URI | 설명 | API 비용 |
API 사용량 |
| 현재 사용량 제한 상태: 사용된 호출, 남은 횟수, 윈도우 초기화 | 0 |
예산 요약 |
| 계좌, 잔액, 카테고리 그룹을 포함한 예산 개요 | 1 |
계좌 목록 |
| 유형, 잔액, 정리된/정리되지 않은 잔액을 포함한 모든 계좌 | 1 |
월별 카테고리 |
| 예산, 활동, 잔액을 포함한 해당 월의 모든 카테고리 | 1 |
프롬프트
프롬프트는 사용자가 일반적인 예산 관리 작업을 수행할 때 호출할 수 있는 가이드 워크플로우 템플릿입니다. LLM에게 어떤 도구를 호출하고 결과를 어떻게 해석해야 하는지 지시합니다.
프롬프트 | 인수 | 설명 |
|
| 예산 월 검토: 초과 지출 카테고리, 지출 차이, 자금 부족 목표, 신용카드 불일치 |
|
| 미분류, 미승인, 중복 및 비정상적인 금액에 대한 거래 감사 |
|
| 가이드 워크스루: 계좌, 카테고리, 목표, 예약 거래, 자금 할당 |
|
| 카테고리 분석, 예산 대비 실제 지출, 상위 수취인, 수입 대비 지출 |
|
| 신용카드 결제 카테고리 잔액 감사 (사전 테스트 후 적용 확인 흐름) |
개발
npm run dev # Watch mode with tsx
npm run build # Compile TypeScript
npm start # Run compiled server라이선스
MIT
Available Tools
47 toolsaudit_credit_card_paymentsAudit Credit Card PaymentsA
[Variable API calls] [Workflow] Audits credit card payment categories by comparing each card's month-end balance against the payment category's available balance. Recommends exact budgeted amount corrections, accounting for cascading effects across months. Audit costs 3 + C + M API calls (C = credit cards, M = months). Set apply=true to automatically fix mismatches (adds 1 API call per mismatch).
Inputs: budget_id, since_month, account_id, apply.
create_accountCreate AccountB
[1 API call] Create a new account in a budget
Inputs: name (required), type (required), balance (required), budget_id.
create_categoryCreate CategoryB
[1 API call] Create a new category in a budget
Inputs: name (required), category_group_id (required), budget_id, note, +2 more.
create_category_groupCreate Category GroupA
[1 API call] Create a new category group in a budget
Inputs: name (required), budget_id.
create_scheduled_transactionCreate Scheduled TransactionA
[1 API call] Create a new scheduled (recurring) transaction. Date must be in the future (up to 5 years).
Inputs: account_id (required), date (required), amount (required), frequency (required), +6 more.
create_transactionCreate TransactionA
[1 API call] Create a new transaction. Amounts are in dollars (positive for inflows, negative for outflows). For split transactions, set category_id to null and provide subtransactions.
Inputs: account_id (required), date (required), amount (required), budget_id, +8 more.
create_transactionsCreate Multiple TransactionsA
[1 API call, bulk] Create multiple transactions at once. Each transaction needs account_id, date, and amount at minimum.
Inputs: transactions (required), budget_id.
delete_scheduled_transactionDelete Scheduled TransactionBDestructive
[1 API call] Delete a scheduled transaction
Inputs: scheduled_transaction_id (required), budget_id.
delete_transactionDelete TransactionBDestructive
[1 API call] Delete a transaction
Inputs: transaction_id (required), budget_id.
get_accountGet AccountBRead-only
[1 API call] Get details for a single account
Inputs: account_id (required), budget_id.
get_api_usageGet API UsageARead-only
[0 API calls] Check current YNAB API usage against the 200 calls/hour rate limit. Use this before batch operations to ensure you have enough budget.
Inputs: no named parameters.
get_budgetGet BudgetARead-only
[1 API call] Get a single budget's full detail including all entities. Use 'last-used' for the most recently accessed budget.
Inputs: budget_id, last_knowledge_of_server.
get_budget_settingsGet Budget SettingsBRead-only
[1 API call] Get a budget's date and currency format settings
Inputs: budget_id.
get_categoryGet CategoryBRead-only
[1 API call] Get details for a single category
Inputs: category_id (required), budget_id.
get_monthGet Budget MonthARead-only
[1 API call] Get detailed info for a single budget month including all category balances. Use 'current' for the current month.
Inputs: month (required), budget_id.
get_month_categoryGet Month CategoryBRead-only
[1 API call] Get a category's budget details for a specific month
Inputs: month (required), category_id (required), budget_id.
get_month_money_movement_groupsGet Month Money Movement GroupsBRead-only
[1 API call] Get money movement groups for a specific month
Inputs: month (required), budget_id.
get_month_money_movementsGet Month Money MovementsBRead-only
[1 API call] Get money movements for a specific month
Inputs: month (required), budget_id.
get_payeeGet PayeeBRead-only
[1 API call] Get details for a single payee
Inputs: payee_id (required), budget_id.
get_payee_locationGet Payee LocationBRead-only
[1 API call] Get a single payee location by ID
Inputs: payee_location_id (required), budget_id.
get_payee_locations_for_payeeGet Locations for PayeeBRead-only
[1 API call] Get all GPS locations for a specific payee
Inputs: payee_id (required), budget_id.
get_scheduled_transactionGet Scheduled TransactionBRead-only
[1 API call] Get details for a single scheduled transaction
Inputs: scheduled_transaction_id (required), budget_id.
get_transactionGet TransactionBRead-only
[1 API call] Get details for a single transaction
Inputs: transaction_id (required), budget_id.
get_userGet UserBRead-only
[1 API call] Get the authenticated user's information including user ID
Inputs: no named parameters.
import_transactionsImport TransactionsB
[1 API call] Trigger an import of transactions from linked financial institutions
Inputs: budget_id.
list_accountsList AccountsARead-only
[1 API call] List all accounts for a budget including balances and types
Inputs: budget_id, last_knowledge_of_server.
list_account_transactionsList Account TransactionsBRead-only
[1 API call] List transactions for a specific account
Inputs: account_id (required), budget_id, since_date, type, +1 more.
list_budgetsList BudgetsARead-only
[1 API call] List all budgets the user has access to, with optional account info
Inputs: include_accounts.
list_categoriesList CategoriesBRead-only
[1 API call] List all categories grouped by category group for a budget
Inputs: budget_id, last_knowledge_of_server.
list_category_transactionsList Category TransactionsBRead-only
[1 API call] List transactions for a specific category
Inputs: category_id (required), budget_id, since_date, type, +1 more.
list_money_movement_groupsList Money Movement GroupsBRead-only
[1 API call] List all money movement groups for a budget
Inputs: budget_id.
list_money_movementsList Money MovementsBRead-only
[1 API call] List all money movements for a budget (funds moved between categories)
Inputs: budget_id.
list_monthsList Budget MonthsARead-only
[1 API call] List all budget months for a budget, showing income, budgeted, activity, and ready to assign
Inputs: budget_id, last_knowledge_of_server.
list_month_transactionsList Month TransactionsBRead-only
[1 API call] List transactions for a specific month
Inputs: month (required), budget_id, since_date, type, +1 more.
list_payee_locationsList Payee LocationsBRead-only
[1 API call] List all payee GPS locations for a budget
Inputs: budget_id.
list_payeesList PayeesBRead-only
[1 API call] List all payees for a budget
Inputs: budget_id, last_knowledge_of_server.
list_payee_transactionsList Payee TransactionsBRead-only
[1 API call] List transactions for a specific payee
Inputs: payee_id (required), budget_id, since_date, type, +1 more.
list_scheduled_transactionsList Scheduled TransactionsBRead-only
[1 API call] List all scheduled (recurring) transactions for a budget
Inputs: budget_id, last_knowledge_of_server.
list_transactionsList TransactionsARead-only
[1 API call] List transactions for a budget with optional filters. Returns most recent transactions first.
Inputs: budget_id, since_date, type, last_knowledge_of_server.
merge_categoryMerge CategoryADestructive
[Variable API calls] [Workflow] Merges a source category into a target category: re-categorizes all transactions and moves all historical budgeted amounts. Dry run costs 4 + N calls (N = number of budget months). Execution costs additional 1 + 2*M calls (M = months with non-zero budgets). Defaults to dry_run=true to preview changes before executing. After merging, the source category will have zero transactions and zero budgeted amounts across all months - you can then manually hide/delete it in the YNAB app.
Inputs: source_category_id (required), target_category_id (required), budget_id, dry_run.
update_categoryUpdate CategoryB
[1 API call] Update an existing category's name, note, or goal
Inputs: category_id (required), budget_id, name, note, +2 more.
update_category_groupUpdate Category GroupB
[1 API call] Update a category group's name
Inputs: category_group_id (required), name (required), budget_id.
update_month_categoryUpdate Month Category BudgetA
[1 API call] Update the budgeted/assigned amount for a category in a specific month. This is how you allocate money to categories.
Inputs: month (required), category_id (required), budgeted (required), budget_id.
update_payeeUpdate PayeeB
[1 API call] Update a payee's name
Inputs: payee_id (required), name (required), budget_id.
update_scheduled_transactionUpdate Scheduled TransactionB
[1 API call] Update an existing scheduled transaction
Inputs: scheduled_transaction_id (required), account_id (required), date (required), budget_id, +7 more.
update_transactionUpdate TransactionC
[1 API call] Update an existing transaction
Inputs: transaction_id (required), budget_id, account_id, date, +8 more.
update_transactionsBulk Update TransactionsA
[1 API call, bulk] Update multiple transactions at once. Each must include either id or import_id to identify the transaction.
Inputs: transactions (required), budget_id.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 47 tools
Most tools have distinct purposes targeting specific resources and actions (e.g., get_account vs. list_accounts), but some overlap exists between list_transactions and more specific listing tools like list_account_transactions, which could cause confusion. The audit_credit_card_payments and merge_category workflows are clearly specialized, reducing ambiguity.
Tool names follow a highly consistent verb_noun pattern throughout, such as create_account, get_budget, list_transactions, and update_category. The two workflow tools (audit_credit_card_payments, merge_category) maintain this structure with descriptive nouns, ensuring predictability across all 47 tools.
With 47 tools, the count is excessive for a budgeting server, leading to a heavy and potentially overwhelming interface. While YNAB's API is comprehensive, many tools (e.g., get_payee_location, list_money_movement_groups) could be consolidated or omitted without losing core functionality, making the set feel bloated.
The tool set provides complete CRUD and lifecycle coverage for YNAB's domain, including accounts, categories, transactions, budgets, and payees. It also includes advanced workflows like auditing and merging, along with utility tools for API usage, ensuring no obvious gaps for agent operations.
Related MCP Connectors
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Personal finance for AI agents — onboard, import statements, categorize & budget over MCP.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
The Ramp MCP server enables users to securely connect Ramp with AI assistants like ChatGPT and Claude to query financial data and take actions using natural language. It transforms Ramp's developer API into a SQL interface that LLMs can query, allowing admins to analyze spend trends, identify cost savings, and run complex SQL analyses on comprehensive datasets (transactions, purchase orders, vendors, users), while all users can manage cards, view transactions, request reimbursements, and get expense policy answers.
Related MCP Servers
- FlicenseAqualityBmaintenanceAn MCP server that provides Large Language Models with access to YNAB (You Need A Budget) budgets, allowing them to fetch budget data including accounts, categories, and category groups.326-
- AlicenseAqualityDmaintenanceA minimal and auditable MCP server that enables local AI assistants to read and manage YNAB budget data. It supports operations like listing accounts, tracking transactions, and moving money between categories while maintaining user privacy.9MIT
- AlicenseCqualityCmaintenanceExposes YNAB API endpoints as MCP tools, allowing AI assistants to manage budgets, accounts, transactions, and more through natural language.41279 PyPI100MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that connects AI assistants to YNAB budgets, enabling natural language queries about finances backed by full API coverage and built-in YNAB methodology knowledge.1MIT