YNAB MCP Server

Instructions

Implementation Reference

• src/tools/GetTransactionsTool.ts:61-142 (handler)

  The main execute function that implements the tool logic: determines budget ID, calls appropriate YNAB API endpoints based on filters (account, category, payee), processes transactions (filter deleted, limit, format amount), and returns JSON response or error.

  export async function execute(input: GetTransactionsInput, api: ynab.API) {
    try {
      const budgetId = getBudgetId(input.budgetId);
      const limit = input.limit || 100;
  
      let rawTransactions: TransactionData[];
  
      // Use the appropriate API method based on filters
      if (input.accountId) {
        const response = await api.transactions.getTransactionsByAccount(
          budgetId,
          input.accountId,
          input.sinceDate,
          mapTransactionType(input.type) as ynab.GetTransactionsByAccountTypeEnum
        );
        rawTransactions = response.data.transactions;
      } else if (input.categoryId) {
        const response = await api.transactions.getTransactionsByCategory(
          budgetId,
          input.categoryId,
          input.sinceDate,
          mapTransactionType(input.type) as ynab.GetTransactionsByCategoryTypeEnum
        );
        rawTransactions = response.data.transactions;
      } else if (input.payeeId) {
        const response = await api.transactions.getTransactionsByPayee(
          budgetId,
          input.payeeId,
          input.sinceDate,
          mapTransactionType(input.type) as ynab.GetTransactionsByPayeeTypeEnum
        );
        rawTransactions = response.data.transactions;
      } else {
        const response = await api.transactions.getTransactions(
          budgetId,
          input.sinceDate,
          mapTransactionType(input.type)
        );
        rawTransactions = response.data.transactions;
      }
  
      // Filter out deleted and apply limit
      const transactions = rawTransactions
        .filter((txn) => !txn.deleted)
        .slice(0, limit)
        .map((txn) => ({
          id: txn.id,
          date: txn.date,
          amount: (txn.amount / 1000).toFixed(2),
          memo: txn.memo,
          approved: txn.approved,
          cleared: txn.cleared,
          account_name: txn.account_name,
          payee_name: txn.payee_name,
          category_name: txn.category_name,
          flag_color: txn.flag_color,
          transfer_account_id: txn.transfer_account_id,
        }));
  
      return {
        content: [{
          type: "text" as const,
          text: JSON.stringify({
            transactions,
            transaction_count: transactions.length,
            total_available: rawTransactions.filter((t) => !t.deleted).length,
          }, null, 2),
        }],
      };
    } catch (error) {
      console.error("Error getting transactions:", error);
      return {
        content: [{
          type: "text" as const,
          text: JSON.stringify({
            success: false,
            error: getErrorMessage(error),
          }, null, 2),
        }],
      };
    }
  }

• src/tools/GetTransactionsTool.ts:7-15 (schema)

  Zod-based input schema defining optional parameters for budget ID, date filter, transaction type, account/category/payee IDs, and limit.

  export const inputSchema = {
    budgetId: z.string().optional().describe("The ID of the budget (optional, defaults to YNAB_BUDGET_ID environment variable)"),
    sinceDate: z.string().optional().describe("Only return transactions on or after this date (ISO format: 2024-01-01)"),
    type: z.enum(["all", "uncategorized", "unapproved"]).optional().describe("Filter by transaction type. Defaults to 'all'."),
    accountId: z.string().optional().describe("Filter to only transactions in this account"),
    categoryId: z.string().optional().describe("Filter to only transactions in this category"),
    payeeId: z.string().optional().describe("Filter to only transactions with this payee"),
    limit: z.number().optional().describe("Maximum number of transactions to return (default: 100)"),
  };

• src/index.ts:87-91 (registration)

  Registers the tool with the MCP server using the exported name, description, schema from GetTransactionsTool, and wraps the execute function with the YNAB API instance.

  server.registerTool(GetTransactionsTool.name, {
    title: "Get Transactions",
    description: GetTransactionsTool.description,
    inputSchema: GetTransactionsTool.inputSchema,
  }, async (input) => GetTransactionsTool.execute(input, api));

• src/index.ts:16-16 (registration)

  Imports the GetTransactionsTool module to access its exports for registration.

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

• src/tools/GetTransactionsTool.ts:27-33 (helper)

  Helper to get budget ID from input or environment variable.

  function getBudgetId(inputBudgetId?: string): string {
    const budgetId = inputBudgetId || process.env.YNAB_BUDGET_ID || "";
    if (!budgetId) {
      throw new Error("No budget ID provided. Please provide a budget ID or set the YNAB_BUDGET_ID environment variable.");
    }
    return budgetId;
  }