YNAB MCP Server

Instructions

Implementation Reference

• src/index.ts:53-55 (handler)

  Core implementation of list_categories tool in YNABClient class: fetches category groups from YNAB API endpoint.

  async listCategories(budgetId: string) {
    return this.request<{ category_groups: any[] }>(`/budgets/${budgetId}/categories`);
  }

• src/index.ts:194-204 (registration)

  Registration of the list_categories tool in the tools array, including name, description, and input schema definition.

  {
    name: "list_categories",
    description: "Get all categories for a budget, grouped by category group. Includes budgeted amounts and activity.",
    inputSchema: {
      type: "object" as const,
      properties: {
        budget_id: { type: "string", description: "The budget ID" },
      },
      required: ["budget_id"],
    },
  },

• src/index.ts:116-118 (schema)

  Zod schema used for input validation of budget_id parameter in list_categories handler.

  const BudgetIdSchema = z.object({
    budget_id: z.string().describe("The budget ID (use 'last-used' for most recent)"),
  });

• src/index.ts:337-341 (handler)

  Specific handler case in CallToolRequestSchema dispatcher that validates input and invokes the listCategories method.

  case "list_categories": {
    const { budget_id } = BudgetIdSchema.parse(args);
    result = await client.listCategories(budget_id);
    break;
  }