YNAB MCP Server

Instructions

Implementation Reference

• src/tools/ListAccountsTool.ts:25-69 (handler)

  The main handler function that fetches accounts from the YNAB API, filters and formats them, and returns a JSON response.

  export async function execute(input: ListAccountsInput, api: ynab.API) {
    try {
      const budgetId = getBudgetId(input.budgetId);
      const includeClosedAccounts = input.includeClosedAccounts ?? false;
  
      console.error(`Listing accounts for budget ${budgetId}`);
      const response = await api.accounts.getAccounts(budgetId);
  
      // Filter and format accounts
      const accounts = response.data.accounts
        .filter((account) => !account.deleted && (includeClosedAccounts || !account.closed))
        .map((account) => ({
          id: account.id,
          name: account.name,
          type: account.type,
          on_budget: account.on_budget,
          closed: account.closed,
          balance: (account.balance / 1000).toFixed(2),
          cleared_balance: (account.cleared_balance / 1000).toFixed(2),
          uncleared_balance: (account.uncleared_balance / 1000).toFixed(2),
          transfer_payee_id: account.transfer_payee_id,
        }));
  
      return {
        content: [{
          type: "text" as const,
          text: JSON.stringify({
            accounts,
            account_count: accounts.length,
          }, null, 2),
        }],
      };
    } catch (error) {
      console.error("Error listing accounts:", error);
      return {
        content: [{
          type: "text" as const,
          text: JSON.stringify({
            success: false,
            error: getErrorMessage(error),
          }, null, 2),
        }],
      };
    }
  }

• src/tools/ListAccountsTool.ts:5-10 (schema)

  Defines the tool's name, description, and input schema with Zod validators.

  export const name = "ynab_list_accounts";
  export const description = "Lists all accounts in a budget. Useful for finding account IDs when creating transactions.";
  export const inputSchema = {
    budgetId: z.string().optional().describe("The ID of the budget (optional, defaults to YNAB_BUDGET_ID environment variable)"),
    includeClosedAccounts: z.boolean().optional().describe("Include closed accounts in the list (default: false)"),
  };

• src/index.ts:105-109 (registration)

  Registers the ynab_list_accounts tool with the MCP server using its name, description, input schema, and a wrapper around the execute function.

  server.registerTool(ListAccountsTool.name, {
    title: "List Accounts",
    description: ListAccountsTool.description,
    inputSchema: ListAccountsTool.inputSchema,
  }, async (input) => ListAccountsTool.execute(input, api));