YNAB MCP Server

Instructions

Implementation Reference

• src/index.ts:61-92 (handler)

  Core handler function in YNABClient class that implements the list_transactions tool logic by querying the YNAB API and applying client-side filters.

  async listTransactions(budgetId: string, params?: {
    sinceDate?: string;
    type?: string;
    categoryId?: string;
    payeeId?: string;
    accountId?: string;
  }) {
    let path = `/budgets/${budgetId}/transactions`;
    const queryParams: string[] = [];
  
    if (params?.sinceDate) queryParams.push(`since_date=${params.sinceDate}`);
    if (params?.type) queryParams.push(`type=${params.type}`);
  
    if (queryParams.length > 0) {
      path += `?${queryParams.join("&")}`;
    }
  
    let result = await this.request<{ transactions: any[] }>(path);
  
    // Client-side filtering for category and payee
    if (params?.categoryId) {
      result.transactions = result.transactions.filter(t => t.category_id === params.categoryId);
    }
    if (params?.payeeId) {
      result.transactions = result.transactions.filter(t => t.payee_id === params.payeeId);
    }
    if (params?.accountId) {
      result.transactions = result.transactions.filter(t => t.account_id === params.accountId);
    }
  
    return result;
  }

• src/index.ts:130-137 (schema)

  Zod schema used for input validation in the list_transactions tool handler.

  const TransactionsSchema = z.object({
    budget_id: z.string().describe("The budget ID"),
    since_date: z.string().optional().describe("Only return transactions on or after this date (ISO format: YYYY-MM-DD)"),
    type: z.enum(["uncategorized", "unapproved"]).optional().describe("Filter by transaction type"),
    category_id: z.string().optional().describe("Filter by category ID"),
    payee_id: z.string().optional().describe("Filter by payee ID"),
    account_id: z.string().optional().describe("Filter by account ID"),
  });

• src/index.ts:217-232 (registration)

  Tool registration entry in the tools array, defining name, description, and input schema for list_tools request.

  {
    name: "list_transactions",
    description: "Get transactions for a budget. Supports filtering by date, type, category, payee, and account.",
    inputSchema: {
      type: "object" as const,
      properties: {
        budget_id: { type: "string", description: "The budget ID" },
        since_date: { type: "string", description: "Only return transactions on or after this date (YYYY-MM-DD)" },
        type: { type: "string", enum: ["uncategorized", "unapproved"], description: "Filter by transaction type" },
        category_id: { type: "string", description: "Filter by category ID" },
        payee_id: { type: "string", description: "Filter by payee ID" },
        account_id: { type: "string", description: "Filter by account ID" },
      },
      required: ["budget_id"],
    },
  },

• src/index.ts:349-359 (handler)

  Dispatch handler in the main CallToolRequestSchema handler that parses input and invokes the listTransactions method.

  case "list_transactions": {
    const params = TransactionsSchema.parse(args);
    result = await client.listTransactions(params.budget_id, {
      sinceDate: params.since_date,
      type: params.type,
      categoryId: params.category_id,
      payeeId: params.payee_id,
      accountId: params.account_id,
    });
    break;
  }