List Payees
ynab_list_payeesRetrieve all payees from a YNAB budget to find specific payee IDs needed for creating or managing transactions.
Instructions
Lists all payees in a budget. Useful for finding payee IDs when creating transactions.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| budgetId | No | The ID of the budget (optional, defaults to YNAB_BUDGET_ID environment variable) |
Implementation Reference
- src/tools/ListPayeesTool.ts:23-60 (handler)The main handler function 'execute' that fetches payees from the YNAB API for the given budget, filters out deleted payees, formats the response as JSON, and handles errors.
export async function execute(input: ListPayeesInput, api: ynab.API) { try { const budgetId = getBudgetId(input.budgetId); console.error(`Listing payees for budget ${budgetId}`); const response = await api.payees.getPayees(budgetId); // Filter out deleted payees and format the response const payees = response.data.payees .filter((payee) => !payee.deleted) .map((payee) => ({ id: payee.id, name: payee.name, transfer_account_id: payee.transfer_account_id, })); return { content: [{ type: "text" as const, text: JSON.stringify({ payees, payee_count: payees.length, }, null, 2), }], }; } catch (error) { console.error("Error listing payees:", error); return { content: [{ type: "text" as const, text: JSON.stringify({ success: false, error: getErrorMessage(error), }, null, 2), }], }; } } - src/tools/ListPayeesTool.ts:7-9 (schema)Input schema definition for the tool using Zod, specifying optional budgetId.
export const inputSchema = { budgetId: z.string().optional().describe("The ID of the budget (optional, defaults to YNAB_BUDGET_ID environment variable)"), }; - src/index.ts:81-85 (registration)Registers the 'ynab_list_payees' tool on the MCP server, providing title, description, inputSchema, and the execute handler wrapped with the YNAB API instance.
server.registerTool(ListPayeesTool.name, { title: "List Payees", description: ListPayeesTool.description, inputSchema: ListPayeesTool.inputSchema, }, async (input) => ListPayeesTool.execute(input, api)); - src/tools/ListPayeesTool.ts:15-21 (helper)Helper function to retrieve or default the 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; }