ynab-mcp-server: Skill for Claude Code

Adding New Tools

Before adding a tool

Check whether the behavior fits as an option on an existing tool (a new filter, date bound, or output mode) before creating a new one. Add a new tool only when no existing tool covers the same data and intent, and say in the PR which existing tools were considered and why they didn't fit. Overlapping tools make the model more likely to pick the wrong one.

1. Create src/tools/MyTool.ts:

import { z } from "zod";
import * as ynab from "ynab";
import { resolvePlanId } from "./planId.js";

export const name = "my_tool";
export const description = "What this tool does";
export const inputSchema = {
  planId: z.string().optional().describe("The plan ID (optional, defaults to YNAB_PLAN_ID; budgetId is a deprecated alias)"),
  budgetId: z.string().optional().describe("Deprecated alias of planId (still accepted)"),
  requiredParam: z.string().describe("Description of required param"),
};

interface MyToolInput {
  planId?: string;
  budgetId?: string;
  requiredParam: string;
}

export async function execute(input: MyToolInput, api: ynab.API) {
  try {
    const planId = resolvePlanId(input);
    const result = await api.someMethod(planId, input.requiredParam);

    return {
      content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }]
    };
  } catch (error) {
    return {
      content: [{ type: "text" as const, text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}` }]
    };
  }
}

1. Register in src/registry.ts — import the module and add it to the tools array. Both entry points build from this one list, so registering here serves the tool from the stdio server and the Cloudflare Worker alike.

import * as MyTool from "./tools/MyTool.js";

export const tools: ToolEntry[] = [
  // ...
  { title: "My Tool", module: MyTool, writes: false },
];

Set writes: true for any tool that changes data in YNAB. YNAB_READ_ONLY filters on that flag, so a mislabelled tool would be exposed in a deployment meant to be read-only.