YNAB MCP Starter

Production-style TypeScript starter repo for a read-only YNAB MCP server.

This starter is intentionally small and explicit:

• Node.js 18+
• TypeScript with strict compiler settings
• Zod-validated tool inputs and outputs
• Read-only YNAB API client with retries and timeout handling
• Unit tests with mocked YNAB responses
• Clear TODO markers where MCP transport wiring should be connected

What This Repo Includes

src/
  clients/   YNAB API client, environment config, and error types
  schemas/   strict Zod schemas for tool contracts
  server/    MCP server composition and transport TODO placeholders
  tools/     read-only business logic for each YNAB capability
  types/     shared API and service types
tests/       unit tests with mocked API responses

Implemented read-only capabilities:

• list budgets
• list accounts
• list categories
• list recent transactions
• find uncategorized transactions
• monthly spend by category

Write access is intentionally not implemented.

Setup

1. Install dependencies:

npm install

2. Copy the example environment file:

cp .env.example .env

3. Set your YNAB token in .env:

YNAB_TOKEN=your-token-here

4. Run local development mode:

npm run dev

Scripts

• npm run build compiles TypeScript into dist/
• npm run dev runs the starter entrypoint with file watching
• npm run lint runs ESLint
• npm run test runs unit tests with Vitest
• npm run typecheck runs TypeScript in no-emit mode

MCP Wiring

The repo includes the server composition layer, but it does not lock you into one transport yet.

Look for TODO comments in:

• src/server/index.ts
• src/server/registerTools.ts

That is where you should:

1. Instantiate the MCP server
2. Register tool definitions and schemas
3. Connect stdio, SSE, or another transport
4. Add structured logging and operational hooks

Security Notes

• This starter expects a YNAB_TOKEN personal access token in environment variables.
• Never hardcode the token in source files, tests, prompts, or logs.
• Keep the token scoped to read-only operational use and rotate it if it is exposed.
• Avoid logging raw YNAB API responses in production because they may contain transaction memos or other sensitive financial metadata.
• This starter only performs GET requests to the YNAB API. No write endpoints are implemented.

Design Notes

• The YNAB client centralizes retries, timeout handling, and error normalization.
• Tool modules are isolated from HTTP details and operate on a small service interface.
• Zod schemas validate both tool inputs and tool outputs to catch drift early.
• Money amounts are exposed in both YNAB milliunits and human-friendly decimal amounts.
• Monthly category spend only counts outflows for the requested month.

Example Prompts

• "List my YNAB budgets."
• "Show the accounts in budget budget-id-123."
• "List categories for budget budget-id-123."
• "Show the most recent 20 transactions in budget budget-id-123."
• "Find uncategorized transactions in budget budget-id-123 since 2026-04-01."
• "Summarize monthly spend by category for budget budget-id-123 in 2026-04."

Testing

The tests mock YNAB API responses so you can validate behavior without a live token:

npm run test

Production Hardening Ideas

• Add request correlation IDs and structured logs
• Add metrics around retries, rate limiting, and latency
• Add integration tests against a mocked HTTP layer
• Add result pagination controls if your MCP client expects larger result sets
• Add a secrets manager integration instead of local .env files for deployment