@oliverames/ynab-mcp-server 1.0.0 → 1.2.0

package/README.md

@@ -0,0 +1,318 @@
+<p align="center">
+  <img src="https://api.ynab.com/papi/logo_api_meadow.svg" alt="YNAB API" width="200">
+</p>
+
+<h1 align="center">YNAB MCP Server</h1>
+
+<p align="center">
+  <strong>The complete Model Context Protocol server for YNAB</strong><br>
+  <em>Give your AI assistant full access to your budget</em>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@oliverames/ynab-mcp-server"><img src="https://img.shields.io/npm/v/@oliverames/ynab-mcp-server" alt="npm version"></a>
+  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-blue" alt="MCP compatible"></a>
+  <a href="https://api.ynab.com"><img src="https://img.shields.io/badge/YNAB%20API-v1.79-green" alt="YNAB API v1.79"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-brightgreen" alt="License: MIT"></a>
+</p>
+
+---
+
+**43 tools. 100% API coverage. Zero configuration.**
+
+Connect any MCP-compatible AI assistant — Claude, GPT, or your own agents — to your YNAB budget. Read transactions, categorize spending, manage accounts, review scheduled payments, track money movements, and more. All monetary values are automatically converted between dollars and YNAB's internal milliunits format so the AI never has to think about it.
+
+Built on the [official YNAB JavaScript SDK](https://github.com/ynab/ynab-sdk-js) with direct API calls for the newest endpoints (category creation, category groups, money movements) that the SDK hasn't caught up with yet.
+
+---
+
+## Quick Start
+
+### 1. Get a YNAB Personal Access Token
+
+Go to [YNAB Developer Settings](https://app.ynab.com/settings/developer) and create a new personal access token.
+
+### 2. Configure your MCP client
+
+**Claude Desktop** (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "ynab": {
+      "command": "npx",
+      "args": ["-y", "@oliverames/ynab-mcp-server"],
+      "env": {
+        "YNAB_API_TOKEN": "your-token-here"
+      }
+    }
+  }
+}
+```
+
+**Claude Code** (`.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "ynab": {
+      "command": "npx",
+      "args": ["-y", "@oliverames/ynab-mcp-server"],
+      "env": {
+        "YNAB_API_TOKEN": "your-token-here"
+      }
+    }
+  }
+}
+```
+
+Or install globally and point to the binary directly:
+
+```bash
+npm install -g @oliverames/ynab-mcp-server
+```
+
+```json
+{
+  "mcpServers": {
+    "ynab": {
+      "command": "ynab-mcp-server",
+      "env": {
+        "YNAB_API_TOKEN": "your-token-here",
+        "YNAB_BUDGET_ID": "optional-default-budget-id"
+      }
+    }
+  }
+}
+```
+
+That's it. Your AI can now talk to YNAB.
+
+---
+
+## What You Can Do
+
+| Ask your AI... | What happens under the hood |
+|---|---|
+| "How much did I spend on groceries this month?" | `search_categories` → `get_month_category` |
+| "Show me all unapproved transactions" | `review_unapproved` groups by readiness |
+| "Log a $50 Costco trip under groceries" | `search_payees` → `search_categories` → `create_transaction` |
+| "Set up monthly $1,500 rent on the 1st" | `create_scheduled_transaction` with `monthly` frequency |
+| "Move $200 from emergency fund to dining" | `search_categories` → `update_month_category` (x2) |
+| "Categorize all my Amazon orders from this week" | `get_transactions` (filtered) → `update_transactions` (batch) |
+| "Create a 'Side Projects' spending category" | `search_categories` (find group) → `create_category` |
+| "How has my budget been re-allocated this month?" | `get_money_movements_by_month` |
+| "What recurring payments do I have?" | `list_scheduled_transactions` |
+| "Import my latest bank transactions" | `import_transactions` triggers linked account sync |
+
+---
+
+## Features
+
+**Complete YNAB API v1.79 coverage** with 43 tools:
+
+| Resource | Tools | Capabilities |
+|----------|-------|-------------|
+| **Budgets** | 4 | List, view details, settings |
+| **Accounts** | 3 | List, view, create |
+| **Categories** | 9 | Full CRUD, groups, search, goals, monthly budgets |
+| **Payees** | 4 | List, view, rename, search |
+| **Payee Locations** | 3 | GPS coordinates for mobile transactions |
+| **Months** | 2 | Monthly summaries with per-category breakdown |
+| **Money Movements** | 4 | Budget re-allocation tracking |
+| **Transactions** | 8 | Full CRUD, bulk ops, split transactions, multi-filter |
+| **Scheduled Transactions** | 5 | Full CRUD for recurring transactions |
+| **Convenience** | 1 | Unapproved transaction review workflow |
+
+### Design Decisions
+
+- **Dollar amounts everywhere** — inputs and outputs are in dollars (`-12.34`), never milliunits (`-12340`). Conversion is automatic and transparent.
+- **Smart budget resolution** — set `YNAB_BUDGET_ID` for a default, or omit it to auto-resolve to your last-used budget. Every tool accepts an optional `budgetId` override.
+- **Split transactions** — first-class support for subtransactions in create, read, and format operations.
+- **Bulk operations** — `create_transactions` and `update_transactions` handle arrays in a single API call.
+- **Fetch-then-merge updates** — scheduled transaction updates (which use PUT semantics) automatically fetch the current state and merge your changes, so you only specify what changed.
+- **Fuzzy search** — `search_categories` and `search_payees` do case-insensitive partial matching across all entries.
+- **Approval workflow** — `review_unapproved` groups transactions into "ready to approve" (has category) and "needs attention" (uncategorized), with a built-in warning against approving uncategorized entries.
+
+---
+
+## Tools Reference
+
+### User & Budgets
+
+| Tool | Description |
+|------|-------------|
+| `get_user` | Get the authenticated user |
+| `list_budgets` | List all budgets with IDs, names, and date ranges |
+| `get_budget` | Get budget summary (name, currency, account/category/payee counts) |
+| `get_budget_settings` | Get currency and date format settings |
+
+### Accounts
+
+| Tool | Description |
+|------|-------------|
+| `list_accounts` | List all accounts with balances in dollars |
+| `get_account` | Get details for a specific account |
+| `create_account` | Create a new account (checking, savings, creditCard, mortgage, etc.) |
+
+**Supported account types:** `checking`, `savings`, `cash`, `creditCard`, `lineOfCredit`, `otherAsset`, `otherLiability`, `mortgage`, `autoLoan`, `studentLoan`, `personalLoan`, `medicalDebt`, `otherDebt`
+
+### Categories & Category Groups
+
+| Tool | Description |
+|------|-------------|
+| `list_categories` | List all category groups and their categories with budgeted/activity/balance |
+| `get_category` | Get full category details including goal progress and cadence |
+| `get_month_category` | Get category budget for a specific month |
+| `update_month_category` | Set the budgeted amount for a category in a month |
+| `update_category` | Update name, note, goal target, or move to a different group |
+| `create_category` | Create a new category in an existing group (with optional goal) |
+| `create_category_group` | Create a new category group |
+| `update_category_group` | Rename a category group |
+| `search_categories` | Case-insensitive partial name search (e.g., "groc" finds "Groceries") |
+
+### Payees
+
+| Tool | Description |
+|------|-------------|
+| `list_payees` | List all payees with transfer account mappings |
+| `get_payee` | Get payee details |
+| `update_payee` | Rename a payee |
+| `search_payees` | Case-insensitive partial name search |
+
+### Payee Locations
+
+| Tool | Description |
+|------|-------------|
+| `list_payee_locations` | List all payee locations (GPS coordinates from mobile app) |
+| `get_payee_location` | Get a specific payee location |
+| `get_payee_locations_by_payee` | Get all locations for a specific payee |
+
+### Months
+
+| Tool | Description |
+|------|-------------|
+| `list_months` | List budget months with income, budgeted, activity, to-be-budgeted, age of money |
+| `get_month` | Get month detail with per-category budget/activity/balance breakdown |
+
+### Money Movements
+
+| Tool | Description |
+|------|-------------|
+| `list_money_movements` | List all money movements (budget re-allocations between categories) |
+| `get_money_movements_by_month` | Get money movements for a specific month |
+| `list_money_movement_groups` | List all money movement groups (batched re-allocations) |
+| `get_money_movement_groups_by_month` | Get money movement groups for a specific month |
+
+### Transactions
+
+| Tool | Description |
+|------|-------------|
+| `get_transactions` | Get transactions with filters: by account, category, payee, month, or status (`unapproved`/`uncategorized`) |
+| `get_transaction` | Get a single transaction by ID (includes subtransactions) |
+| `create_transaction` | Create a transaction with optional split (subtransactions must sum to total) |
+| `create_transactions` | Bulk create multiple transactions in a single API call |
+| `update_transaction` | Partial update — only specified fields change |
+| `update_transactions` | Batch update multiple transactions at once |
+| `delete_transaction` | Delete a transaction |
+| `import_transactions` | Trigger import from linked bank accounts |
+
+### Scheduled Transactions
+
+| Tool | Description |
+|------|-------------|
+| `list_scheduled_transactions` | List all recurring transactions |
+| `get_scheduled_transaction` | Get a specific scheduled transaction |
+| `create_scheduled_transaction` | Create a recurring transaction with frequency |
+| `update_scheduled_transaction` | Update (fetch-then-merge preserves unchanged fields) |
+| `delete_scheduled_transaction` | Delete a scheduled transaction |
+
+**Supported frequencies:** `never`, `daily`, `weekly`, `everyOtherWeek`, `twiceAMonth`, `every4Weeks`, `monthly`, `everyOtherMonth`, `every3Months`, `every4Months`, `twiceAYear`, `yearly`, `everyOtherYear`
+
+### Convenience
+
+| Tool | Description |
+|------|-------------|
+| `review_unapproved` | Get unapproved transactions grouped by readiness: "ready to approve" (categorized) vs. "needs category first" (uncategorized). Includes a warning against blind approval. |
+
+---
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `YNAB_API_TOKEN` | Yes | [Personal access token](https://app.ynab.com/settings/developer) from YNAB Developer Settings |
+| `YNAB_BUDGET_ID` | No | Default budget ID. If omitted, uses `"last-used"` (your most recently accessed budget). Run `list_budgets` to find IDs. |
+
+---
+
+## Amount Handling
+
+All amounts in tool inputs and outputs are in **dollars** (e.g., `-12.34` for a $12.34 outflow). The server converts to/from YNAB's internal milliunits format automatically.
+
+| Direction | Sign | Example |
+|-----------|------|---------|
+| Outflow (spending) | Negative | `-50.00` |
+| Inflow (income) | Positive | `2500.00` |
+| Transfer out | Negative | `-1000.00` |
+| Transfer in | Positive | `1000.00` |
+
+---
+
+## Rate Limiting
+
+The YNAB API allows **200 requests per hour** per access token, enforced on a rolling window. Each tool call typically uses one API request (except `update_scheduled_transaction` which uses two — a GET to fetch current state, then a PUT to merge changes). The server surfaces rate limit errors as standard MCP error responses.
+
+---
+
+## Architecture
+
+```
+┌─────────────────────┐     ┌──────────────────┐     ┌──────────────┐
+│  AI Assistant       │────▶│  YNAB MCP Server │────▶│  YNAB API    │
+│  (Claude, GPT, etc) │◀────│  (this package)  │◀────│  api.ynab.com│
+└─────────────────────┘     └──────────────────┘     └──────────────┘
+         MCP                    stdio transport           HTTPS/REST
+```
+
+- **Transport:** stdio (standard MCP server pattern)
+- **Auth:** Bearer token via `YNAB_API_TOKEN` environment variable
+- **SDK:** Official [`ynab`](https://www.npmjs.com/package/ynab) v2.5+ for core endpoints, direct `fetch` for newer API features
+- **Validation:** All parameters validated with [Zod](https://zod.dev) schemas
+- **Error handling:** API errors are caught, formatted, and returned as MCP error responses with detail messages
+
+---
+
+## Testing
+
+The test suite (43 tests) runs against a live YNAB budget. It creates test data and cleans up after itself:
+
+```bash
+YNAB_API_TOKEN=your-token YNAB_BUDGET_ID=your-budget-id npm test
+```
+
+Tests cover all tool categories: reads, writes, bulk operations, search, split transactions, scheduled transaction CRUD with fetch-then-merge verification, category/group creation, money movements, and payee locations.
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/oliverames/ynab-mcp-server.git
+cd ynab-mcp-server
+npm install
+YNAB_API_TOKEN=your-token npm start
+```
+
+### Dependencies
+
+- [`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk) — MCP server framework
+- [`ynab`](https://www.npmjs.com/package/ynab) — Official YNAB JavaScript client
+
+Zero additional dependencies. No build step. Pure ESM.
+
+---
+
+## License
+
+MIT

package/index.js

@@ -19,8 +19,7 @@ const DEFAULT_BUDGET_ID = process.env.YNAB_BUDGET_ID;
 // --- Helpers ---
 
 function resolveBudgetId(input) {
-  const id = input || DEFAULT_BUDGET_ID;
-  if (!id) throw new Error("budgetId is required (pass it or set YNAB_BUDGET_ID env var)");
+  const id = input || DEFAULT_BUDGET_ID || "last-used";
   return id;
 }
 
@@ -40,16 +39,38 @@ async function run(fn) {
   try {
     return await fn();
   } catch (e) {
-    const msg = e?.error?.detail || e?.message || String(e);
-    return { content: [{ type: "text", text: `Error: ${msg}` }] };
+    const detail = e?.error?.detail;
+    const name = e?.error?.name;
+    const msg = detail
+      ? (name ? `${name}: ${detail}` : detail)
+      : (e?.message || String(e));
+    return { content: [{ type: "text", text: `Error: ${msg}` }], isError: true };
   }
 }
 
+// Direct API helper for endpoints not yet in the ynab SDK
+const BASE_URL = "https://api.ynab.com/v1";
+async function ynabFetch(path, { method = "GET", body } = {}) {
+  const opts = {
+    method,
+    headers: { Authorization: `Bearer ${API_TOKEN}`, "Content-Type": "application/json" },
+  };
+  if (body) opts.body = JSON.stringify(body);
+  const res = await fetch(`${BASE_URL}${path}`, opts);
+  const json = await res.json();
+  if (!res.ok) {
+    const err = new Error(json?.error?.detail || `HTTP ${res.status}`);
+    err.error = json?.error;
+    throw err;
+  }
+  return json.data;
+}
+
 // --- Server ---
 
 const server = new McpServer({
   name: "ynab-mcp-server",
-  version: "1.0.0",
+  version: "1.2.0",
 });
 
 // ==================== User & Budgets ====================
@@ -61,16 +82,16 @@ server.tool("get_user", "Get the authenticated user", {}, () =>
   })
 );
 
-server.tool("list_budgets", "List all budgets", {}, () =>
+server.tool("list_budgets", "List all budgets. Use a budget ID from the results in other tools, or omit budgetId to use the last-used budget.", {}, () =>
   run(async () => {
     const { data } = await api.budgets.getBudgets();
-    return ok(data.budgets.map((b) => ({ id: b.id, name: b.name, last_modified_on: b.last_modified_on })));
+    return ok(data.budgets.map((b) => ({ id: b.id, name: b.name, last_modified_on: b.last_modified_on, first_month: b.first_month, last_month: b.last_month })));
   })
 );
 
 server.tool(
   "get_budget",
-  "Get full budget details including accounts, categories, and payees",
+  "Get a budget summary including name, currency format, and account/category/payee counts",
   { budgetId: z.string().optional().describe("Budget ID (uses default if not provided)") },
   ({ budgetId }) =>
     run(async () => {
@@ -79,6 +100,10 @@ server.tool(
       return ok({
         id: b.id,
         name: b.name,
+        last_modified_on: b.last_modified_on,
+        first_month: b.first_month,
+        last_month: b.last_month,
+        date_format: b.date_format,
         currency_format: b.currency_format,
         accounts: b.accounts?.length,
         categories: b.categories?.length,
@@ -100,6 +125,26 @@ server.tool(
 
 // ==================== Accounts ====================
 
+function formatAccount(a) {
+  const out = {
+    id: a.id,
+    name: a.name,
+    type: a.type,
+    on_budget: a.on_budget,
+    closed: a.closed,
+    balance: dollars(a.balance),
+    cleared_balance: dollars(a.cleared_balance),
+    uncleared_balance: dollars(a.uncleared_balance),
+    transfer_payee_id: a.transfer_payee_id,
+    direct_import_linked: a.direct_import_linked,
+    direct_import_in_error: a.direct_import_in_error,
+    last_reconciled_at: a.last_reconciled_at,
+    deleted: a.deleted,
+  };
+  if ("note" in a) out.note = a.note;
+  return out;
+}
+
 server.tool(
   "list_accounts",
   "List all accounts in a budget",
@@ -107,18 +152,7 @@ server.tool(
   ({ budgetId }) =>
     run(async () => {
       const { data } = await api.accounts.getAccounts(resolveBudgetId(budgetId));
-      return ok(
-        data.accounts.map((a) => ({
-          id: a.id,
-          name: a.name,
-          type: a.type,
-          on_budget: a.on_budget,
-          closed: a.closed,
-          balance: dollars(a.balance),
-          cleared_balance: dollars(a.cleared_balance),
-          uncleared_balance: dollars(a.uncleared_balance),
-        }))
-      );
+      return ok(data.accounts.map(formatAccount));
     })
 );
 
@@ -132,8 +166,7 @@ server.tool(
   ({ budgetId, accountId }) =>
     run(async () => {
       const { data } = await api.accounts.getAccountById(resolveBudgetId(budgetId), accountId);
-      const a = data.account;
-      return ok({ ...a, balance: dollars(a.balance), cleared_balance: dollars(a.cleared_balance), uncleared_balance: dollars(a.uncleared_balance) });
+      return ok(formatAccount(data.account));
     })
 );
 
@@ -151,12 +184,39 @@ server.tool(
       const { data } = await api.accounts.createAccount(resolveBudgetId(budgetId), {
         account: { name, type, balance: milliunits(bal) },
       });
-      return ok(data.account);
+      return ok(formatAccount(data.account));
     })
 );
 
 // ==================== Categories ====================
 
+function formatCategory(c) {
+  return {
+    id: c.id,
+    category_group_id: c.category_group_id,
+    category_group_name: c.category_group_name,
+    name: c.name,
+    hidden: c.hidden,
+    note: c.note,
+    budgeted: dollars(c.budgeted),
+    activity: dollars(c.activity),
+    balance: dollars(c.balance),
+    goal_type: c.goal_type,
+    goal_day: c.goal_day,
+    goal_cadence: c.goal_cadence,
+    goal_cadence_frequency: c.goal_cadence_frequency,
+    goal_creation_month: c.goal_creation_month,
+    goal_target: dollars(c.goal_target),
+    goal_target_date: c.goal_target_date,
+    goal_percentage_complete: c.goal_percentage_complete,
+    goal_months_to_budget: c.goal_months_to_budget,
+    goal_under_funded: dollars(c.goal_under_funded),
+    goal_overall_funded: dollars(c.goal_overall_funded),
+    goal_overall_left: dollars(c.goal_overall_left),
+    goal_needs_whole_amount: c.goal_needs_whole_amount,
+  };
+}
+
 server.tool(
   "list_categories",
   "List all category groups and their categories",
@@ -176,6 +236,7 @@ server.tool(
             budgeted: dollars(c.budgeted),
             activity: dollars(c.activity),
             balance: dollars(c.balance),
+            goal_type: c.goal_type,
           })),
         }))
       );
@@ -192,8 +253,7 @@ server.tool(
   ({ budgetId, categoryId }) =>
     run(async () => {
       const { data } = await api.categories.getCategoryById(resolveBudgetId(budgetId), categoryId);
-      const c = data.category;
-      return ok({ ...c, budgeted: dollars(c.budgeted), activity: dollars(c.activity), balance: dollars(c.balance), goal_target: dollars(c.goal_target) });
+      return ok(formatCategory(data.category));
     })
 );
 
@@ -208,8 +268,7 @@ server.tool(
   ({ budgetId, month, categoryId }) =>
     run(async () => {
       const { data } = await api.categories.getMonthCategoryById(resolveBudgetId(budgetId), month, categoryId);
-      const c = data.category;
-      return ok({ ...c, budgeted: dollars(c.budgeted), activity: dollars(c.activity), balance: dollars(c.balance) });
+      return ok(formatCategory(data.category));
     })
 );
 
@@ -227,8 +286,94 @@ server.tool(
       const { data } = await api.categories.updateMonthCategory(resolveBudgetId(budgetId), month, categoryId, {
         category: { budgeted: milliunits(budgeted) },
       });
-      const c = data.category;
-      return ok({ ...c, budgeted: dollars(c.budgeted), activity: dollars(c.activity), balance: dollars(c.balance) });
+      return ok(formatCategory(data.category));
+    })
+);
+
+server.tool(
+  "update_category",
+  "Update a category's name, note, goal target, or move it to a different group",
+  {
+    budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
+    categoryId: z.string().describe("Category ID"),
+    name: z.string().optional().describe("New category name"),
+    note: z.string().nullable().optional().describe("Category note (null to clear)"),
+    categoryGroupId: z.string().optional().describe("Move to a different category group"),
+    goalTarget: z.number().nullable().optional().describe("Goal target amount in dollars (only if category already has a goal)"),
+  },
+  ({ budgetId, categoryId, name, note, categoryGroupId, goalTarget }) =>
+    run(async () => {
+      const cat = {};
+      if (name !== undefined) cat.name = name;
+      if (note !== undefined) cat.note = note;
+      if (categoryGroupId !== undefined) cat.category_group_id = categoryGroupId;
+      if (goalTarget !== undefined) cat.goal_target = goalTarget != null ? milliunits(goalTarget) : null;
+
+      const { data } = await api.categories.updateCategory(resolveBudgetId(budgetId), categoryId, {
+        category: cat,
+      });
+      return ok(formatCategory(data.category));
+    })
+);
+
+server.tool(
+  "create_category",
+  "Create a new category in a category group",
+  {
+    budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
+    categoryGroupId: z.string().describe("Category group ID to create the category in"),
+    name: z.string().describe("Category name"),
+    note: z.string().optional().describe("Category note"),
+    goalTarget: z.number().optional().describe("Goal target amount in dollars (creates a 'Needed for Spending' goal)"),
+    goalTargetDate: z.string().optional().describe("Goal target date in ISO format (e.g. 2026-12-01)"),
+  },
+  ({ budgetId, categoryGroupId, name, note, goalTarget, goalTargetDate }) =>
+    run(async () => {
+      const bid = resolveBudgetId(budgetId);
+      const cat = { category_group_id: categoryGroupId, name };
+      if (note !== undefined) cat.note = note;
+      if (goalTarget !== undefined) cat.goal_target = milliunits(goalTarget);
+      if (goalTargetDate !== undefined) cat.goal_target_date = goalTargetDate;
+      const data = await ynabFetch(`/budgets/${bid}/categories`, {
+        method: "POST",
+        body: { category: cat },
+      });
+      return ok(formatCategory(data.category));
+    })
+);
+
+server.tool(
+  "create_category_group",
+  "Create a new category group",
+  {
+    budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
+    name: z.string().describe("Category group name (max 50 characters)"),
+  },
+  ({ budgetId, name }) =>
+    run(async () => {
+      const data = await ynabFetch(`/budgets/${resolveBudgetId(budgetId)}/category_groups`, {
+        method: "POST",
+        body: { category_group: { name } },
+      });
+      return ok(data.category_group);
+    })
+);
+
+server.tool(
+  "update_category_group",
+  "Rename a category group",
+  {
+    budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
+    categoryGroupId: z.string().describe("Category group ID"),
+    name: z.string().describe("New category group name (max 50 characters)"),
+  },
+  ({ budgetId, categoryGroupId, name }) =>
+    run(async () => {
+      const data = await ynabFetch(`/budgets/${resolveBudgetId(budgetId)}/category_groups/${categoryGroupId}`, {
+        method: "PATCH",
+        body: { category_group: { name } },
+      });
+      return ok(data.category_group);
     })
 );
 
@@ -276,6 +421,47 @@ server.tool(
     })
 );
 
+// ==================== Payee Locations ====================
+
+server.tool(
+  "list_payee_locations",
+  "List all payee locations (GPS coordinates where transactions occurred)",
+  { budgetId: z.string().optional().describe("Budget ID (uses default if not provided)") },
+  ({ budgetId }) =>
+    run(async () => {
+      const { data } = await api.payeeLocations.getPayeeLocations(resolveBudgetId(budgetId));
+      return ok(data.payee_locations);
+    })
+);
+
+server.tool(
+  "get_payee_location",
+  "Get a specific payee location",
+  {
+    budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
+    payeeLocationId: z.string().describe("Payee location ID"),
+  },
+  ({ budgetId, payeeLocationId }) =>
+    run(async () => {
+      const { data } = await api.payeeLocations.getPayeeLocationById(resolveBudgetId(budgetId), payeeLocationId);
+      return ok(data.payee_location);
+    })
+);
+
+server.tool(
+  "get_payee_locations_by_payee",
+  "Get all locations for a specific payee",
+  {
+    budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
+    payeeId: z.string().describe("Payee ID"),
+  },
+  ({ budgetId, payeeId }) =>
+    run(async () => {
+      const { data } = await api.payeeLocations.getPayeeLocationsByPayee(resolveBudgetId(budgetId), payeeId);
+      return ok(data.payee_locations);
+    })
+);
+
 // ==================== Months ====================
 
 server.tool(
@@ -292,6 +478,7 @@ server.tool(
           budgeted: dollars(m.budgeted),
           activity: dollars(m.activity),
           to_be_budgeted: dollars(m.to_be_budgeted),
+          age_of_money: m.age_of_money,
         }))
       );
     })
@@ -314,17 +501,88 @@ server.tool(
         budgeted: dollars(m.budgeted),
         activity: dollars(m.activity),
         to_be_budgeted: dollars(m.to_be_budgeted),
+        age_of_money: m.age_of_money,
         categories: m.categories?.map((c) => ({
           id: c.id,
           name: c.name,
+          category_group_name: c.category_group_name,
           budgeted: dollars(c.budgeted),
           activity: dollars(c.activity),
           balance: dollars(c.balance),
+          goal_type: c.goal_type,
+          goal_target: dollars(c.goal_target),
+          goal_under_funded: dollars(c.goal_under_funded),
         })),
       });
     })
 );
 
+// ==================== Money Movements ====================
+
+function formatMoneyMovement(m) {
+  return {
+    id: m.id,
+    month: m.month,
+    moved_at: m.moved_at,
+    note: m.note,
+    money_movement_group_id: m.money_movement_group_id,
+    performed_by_user_id: m.performed_by_user_id,
+    from_category_id: m.from_category_id,
+    to_category_id: m.to_category_id,
+    amount: dollars(m.amount),
+  };
+}
+
+server.tool(
+  "list_money_movements",
+  "List all money movements (budget re-allocations between categories)",
+  { budgetId: z.string().optional().describe("Budget ID (uses default if not provided)") },
+  ({ budgetId }) =>
+    run(async () => {
+      const data = await ynabFetch(`/budgets/${resolveBudgetId(budgetId)}/money_movements`);
+      return ok(data.money_movements.map(formatMoneyMovement));
+    })
+);
+
+server.tool(
+  "get_money_movements_by_month",
+  "Get money movements for a specific month",
+  {
+    budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
+    month: z.string().describe("Month in YYYY-MM-DD format (first of month), or 'current'"),
+  },
+  ({ budgetId, month }) =>
+    run(async () => {
+      const data = await ynabFetch(`/budgets/${resolveBudgetId(budgetId)}/months/${month}/money_movements`);
+      return ok(data.money_movements.map(formatMoneyMovement));
+    })
+);
+
+server.tool(
+  "list_money_movement_groups",
+  "List all money movement groups (batches of related money movements)",
+  { budgetId: z.string().optional().describe("Budget ID (uses default if not provided)") },
+  ({ budgetId }) =>
+    run(async () => {
+      const data = await ynabFetch(`/budgets/${resolveBudgetId(budgetId)}/money_movement_groups`);
+      return ok(data.money_movement_groups);
+    })
+);
+
+server.tool(
+  "get_money_movement_groups_by_month",
+  "Get money movement groups for a specific month",
+  {
+    budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
+    month: z.string().describe("Month in YYYY-MM-DD format (first of month), or 'current'"),
+  },
+  ({ budgetId, month }) =>
+    run(async () => {
+      const data = await ynabFetch(`/budgets/${resolveBudgetId(budgetId)}/months/${month}/money_movement_groups`);
+      return ok(data.money_movement_groups);
+    })
+);
+
 // ==================== Transactions ====================
 
 function formatTransaction(t) {
@@ -344,6 +602,9 @@ function formatTransaction(t) {
     category_id: t.category_id,
     category_name: t.category_name,
     transfer_account_id: t.transfer_account_id,
+    import_id: t.import_id,
+    import_payee_name: t.import_payee_name,
+    debt_transaction_type: t.debt_transaction_type,
     subtransactions: t.subtransactions?.map((s) => ({
       id: s.id,
       amount: dollars(s.amount),
@@ -383,12 +644,8 @@ server.tool(
         const { data } = await api.transactions.getTransactionsByPayee(bid, payeeId, sinceDate, type);
         transactions = data.transactions;
       } else if (month) {
-        // getTransactionsByMonth doesn't exist in SDK — use sinceDate filter
-        const startDate = month;
-        const [y, m] = month.split("-").map(Number);
-        const endDate = new Date(y, m, 0).toISOString().slice(0, 10); // last day of month
-        const { data } = await api.transactions.getTransactions(bid, startDate, type);
-        transactions = data.transactions.filter((t) => t.date <= endDate);
+        const { data } = await api.transactions.getTransactionsByMonth(bid, month, sinceDate, type);
+        transactions = data.transactions;
       } else {
         const { data } = await api.transactions.getTransactions(bid, sinceDate, type);
         transactions = data.transactions;
@@ -414,7 +671,7 @@ server.tool(
 
 server.tool(
   "create_transaction",
-  "Create a new transaction. Amounts are in dollars (positive for inflows, negative for outflows).",
+  "Create a new transaction. Amounts are in dollars (positive for inflows, negative for outflows). Note: future-dated transactions cannot be created here — use create_scheduled_transaction instead.",
   {
     budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
     accountId: z.string().describe("Account ID"),
@@ -427,27 +684,90 @@ server.tool(
     cleared: z.enum(["cleared", "uncleared", "reconciled"]).optional().describe("Cleared status"),
     approved: z.boolean().optional().describe("Whether transaction is approved"),
     flagColor: z.enum(["red", "orange", "yellow", "green", "blue", "purple"]).optional().describe("Flag color"),
+    importId: z.string().optional().describe("Unique import ID for deduplication (max 36 chars). If omitted and the transaction is later imported, duplicates may be created."),
+    subtransactions: z.array(z.object({
+      amount: z.number().describe("Subtransaction amount in dollars"),
+      categoryId: z.string().optional().describe("Category ID"),
+      payeeId: z.string().optional().describe("Payee ID"),
+      payeeName: z.string().optional().describe("Payee name"),
+      memo: z.string().optional().describe("Memo"),
+    })).optional().describe("Split transaction into subtransactions. The subtransaction amounts must sum to the total transaction amount."),
   },
-  ({ budgetId, accountId, date, amount, payeeId, payeeName, categoryId, memo, cleared, approved, flagColor }) =>
+  ({ budgetId, accountId, date, amount, payeeId, payeeName, categoryId, memo, cleared, approved, flagColor, importId, subtransactions }) =>
     run(async () => {
+      const txn = {
+        account_id: accountId,
+        date,
+        amount: milliunits(amount),
+        payee_id: payeeId,
+        payee_name: payeeName,
+        category_id: categoryId,
+        memo,
+        cleared,
+        approved,
+        flag_color: flagColor,
+        import_id: importId,
+      };
+      if (subtransactions) {
+        txn.subtransactions = subtransactions.map((s) => ({
+          amount: milliunits(s.amount),
+          category_id: s.categoryId,
+          payee_id: s.payeeId,
+          payee_name: s.payeeName,
+          memo: s.memo,
+        }));
+      }
       const { data } = await api.transactions.createTransaction(resolveBudgetId(budgetId), {
-        transaction: {
-          account_id: accountId,
-          date,
-          amount: milliunits(amount),
-          payee_id: payeeId,
-          payee_name: payeeName,
-          category_id: categoryId,
-          memo,
-          cleared,
-          approved,
-          flag_color: flagColor,
-        },
+        transaction: txn,
       });
       return ok(formatTransaction(data.transaction));
     })
 );
 
+server.tool(
+  "create_transactions",
+  "Create multiple transactions at once. Amounts are in dollars. Returns created transactions and any duplicate import IDs. Future-dated transactions are not supported — use create_scheduled_transaction instead.",
+  {
+    budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
+    transactions: z.array(z.object({
+      accountId: z.string().describe("Account ID"),
+      date: z.string().describe("Transaction date (YYYY-MM-DD)"),
+      amount: z.number().describe("Amount in dollars (negative for outflows, positive for inflows)"),
+      payeeId: z.string().optional().describe("Payee ID"),
+      payeeName: z.string().optional().describe("Payee name (creates new payee if no payeeId)"),
+      categoryId: z.string().optional().describe("Category ID"),
+      memo: z.string().optional().describe("Transaction memo"),
+      cleared: z.enum(["cleared", "uncleared", "reconciled"]).optional().describe("Cleared status"),
+      approved: z.boolean().optional().describe("Whether transaction is approved"),
+      flagColor: z.enum(["red", "orange", "yellow", "green", "blue", "purple"]).optional().describe("Flag color"),
+      importId: z.string().optional().describe("Unique import ID for deduplication (max 36 chars)"),
+    })).describe("Array of transactions to create"),
+  },
+  ({ budgetId, transactions: txns }) =>
+    run(async () => {
+      const mapped = txns.map((t) => ({
+        account_id: t.accountId,
+        date: t.date,
+        amount: milliunits(t.amount),
+        payee_id: t.payeeId,
+        payee_name: t.payeeName,
+        category_id: t.categoryId,
+        memo: t.memo,
+        cleared: t.cleared,
+        approved: t.approved,
+        flag_color: t.flagColor,
+        import_id: t.importId,
+      }));
+      const { data } = await api.transactions.createTransactions(resolveBudgetId(budgetId), {
+        transactions: mapped,
+      });
+      return ok({
+        created: data.transactions?.map(formatTransaction),
+        duplicate_import_ids: data.duplicate_import_ids,
+      });
+    })
+);
+
 server.tool(
   "update_transaction",
   "Update an existing transaction. Only provided fields are changed. Amounts in dollars.",
@@ -496,7 +816,7 @@ server.tool(
   ({ budgetId, transactionId }) =>
     run(async () => {
       const { data } = await api.transactions.deleteTransaction(resolveBudgetId(budgetId), transactionId);
-      return ok(data.transaction);
+      return ok(formatTransaction(data.transaction));
     })
 );
 
@@ -569,6 +889,16 @@ function formatScheduledTransaction(t) {
     payee_name: t.payee_name,
     category_id: t.category_id,
     category_name: t.category_name,
+    transfer_account_id: t.transfer_account_id,
+    subtransactions: t.subtransactions?.map((s) => ({
+      id: s.id,
+      amount: dollars(s.amount),
+      memo: s.memo,
+      payee_id: s.payee_id,
+      payee_name: s.payee_name,
+      category_id: s.category_id,
+      category_name: s.category_name,
+    })),
   };
 }
 
@@ -631,6 +961,50 @@ server.tool(
     })
 );
 
+server.tool(
+  "update_scheduled_transaction",
+  "Update an existing scheduled transaction. Only provided fields are changed. Amounts in dollars.",
+  {
+    budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
+    scheduledTransactionId: z.string().describe("Scheduled transaction ID"),
+    accountId: z.string().optional().describe("Account ID"),
+    date: z.string().optional().describe("Next occurrence date (YYYY-MM-DD)"),
+    frequency: z.enum(["never", "daily", "weekly", "everyOtherWeek", "twiceAMonth", "every4Weeks", "monthly", "everyOtherMonth", "every3Months", "every4Months", "twiceAYear", "yearly", "everyOtherYear"]).optional().describe("Recurrence frequency"),
+    amount: z.number().optional().describe("Amount in dollars (negative for outflows)"),
+    payeeId: z.string().nullable().optional().describe("Payee ID"),
+    payeeName: z.string().nullable().optional().describe("Payee name"),
+    categoryId: z.string().nullable().optional().describe("Category ID"),
+    memo: z.string().nullable().optional().describe("Memo"),
+    flagColor: z.enum(["red", "orange", "yellow", "green", "blue", "purple"]).nullable().optional().describe("Flag color"),
+  },
+  ({ budgetId, scheduledTransactionId, accountId, date, frequency, amount, payeeId, payeeName, categoryId, memo, flagColor }) =>
+    run(async () => {
+      const bid = resolveBudgetId(budgetId);
+      // PUT replaces the full resource — fetch current values to merge with updates
+      const { data: current } = await api.scheduledTransactions.getScheduledTransactionById(bid, scheduledTransactionId);
+      const existing = current.scheduled_transaction;
+
+      const st = {
+        account_id: accountId ?? existing.account_id,
+        date: date ?? existing.date_next,
+        frequency: frequency ?? existing.frequency,
+        amount: amount !== undefined ? milliunits(amount) : existing.amount,
+        payee_id: payeeId !== undefined ? payeeId : existing.payee_id,
+        payee_name: payeeName !== undefined ? payeeName : existing.payee_name,
+        category_id: categoryId !== undefined ? categoryId : existing.category_id,
+        memo: memo !== undefined ? memo : existing.memo,
+        flag_color: flagColor !== undefined ? flagColor : existing.flag_color,
+      };
+
+      const { data } = await api.scheduledTransactions.updateScheduledTransaction(
+        bid,
+        scheduledTransactionId,
+        { scheduled_transaction: st }
+      );
+      return ok(formatScheduledTransaction(data.scheduled_transaction));
+    })
+);
+
 server.tool(
   "delete_scheduled_transaction",
   "Delete a scheduled transaction",
@@ -641,7 +1015,7 @@ server.tool(
   ({ budgetId, scheduledTransactionId }) =>
     run(async () => {
       const { data } = await api.scheduledTransactions.deleteScheduledTransaction(resolveBudgetId(budgetId), scheduledTransactionId);
-      return ok(data.scheduled_transaction);
+      return ok(formatScheduledTransaction(data.scheduled_transaction));
     })
 );
 
@@ -726,5 +1100,10 @@ server.tool(
 
 // --- Start ---
 
+process.on("uncaughtException", (err) => {
+  console.error("Uncaught exception:", err);
+  process.exit(1);
+});
+
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/package.json

@@ -1,33 +1,21 @@
-{
-  "name": "@oliverames/ynab-mcp-server",
-  "version": "1.0.0",
-  "description": "YNAB MCP server with full API coverage",
-  "type": "module",
-  "main": "index.js",
-  "bin": {
-    "ynab-mcp-server": "index.js"
-  },
-  "files": [
-    "index.js"
-  ],
-  "keywords": [
-    "mcp",
-    "ynab",
-    "budgeting",
-    "model-context-protocol"
-  ],
-  "author": "Oliver Ames",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/oliverames/oliver-claude-marketplace",
-    "directory": "extensions/ynab-mcp-server"
-  },
-  "scripts": {
-    "start": "node index.js"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.1",
-    "ynab": "^2.5.0"
-  }
-}
+{
+  "name": "@oliverames/ynab-mcp-server",
+  "version": "1.2.0",
+  "description": "YNAB MCP server with full API coverage",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "ynab-mcp-server": "index.js"
+  },
+  "files": [
+    "index.js"
+  ],
+  "scripts": {
+    "start": "node index.js",
+    "test": "node test.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "ynab": "^2.5.0"
+  }
+}