ynab_get_payees
Read-onlyIdempotent
List all payees in your YNAB budget to identify transaction recipients. Specify a budget ID or default to your last-used budget.
Instructions
List all payees in the budget.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- src/ynab_mcp_server/server.py:454-483 (handler)The tool ynab_get_payees handler function. Decorated with @mcp.tool, it calls the YNAB API to list all payees, filters out deleted and transfer payees, sorts them alphabetically, and returns a formatted markdown string.
@mcp.tool( name="ynab_get_payees", annotations={ "title": "List Payees", "readOnlyHint": True, "destructiveHint": False, "idempotentHint": True, "openWorldHint": False, } ) async def ynab_get_payees(params: GetPayeesInput) -> str: """List all payees in the budget.""" try: async with YNABClient() as client: payees = await client.get_payees(params.budget_id) payees = [p for p in payees if not p.get("deleted") and not p["name"].startswith("Transfer")] payees = sorted(payees, key=lambda p: p["name"].lower()) result = f"## Payees ({len(payees)} total)\n\n" for p in payees[:100]: result += f"- {p['name']} (`{p['id']}`)\n" if len(payees) > 100: result += f"\n*...and {len(payees) - 100} more*\n" return result except Exception as e: return format_error(e) - src/ynab_mcp_server/server.py:454-462 (registration)The @mcp.tool decorator that registers ynab_get_payees with the MCP server, including annotations for title, readOnlyHint, destructiveHint, idempotentHint, and openWorldHint.
@mcp.tool( name="ynab_get_payees", annotations={ "title": "List Payees", "readOnlyHint": True, "destructiveHint": False, "idempotentHint": True, "openWorldHint": False, } - The GetPayeesInput schema class, which extends BudgetIdInput (with a single budget_id field). Defines the input parameter for the ynab_get_payees tool.
class GetPayeesInput(BudgetIdInput): """Input for listing all payees.""" pass - src/ynab_mcp_server/api.py:333-336 (helper)The API client method get_payees that makes the actual HTTP GET request to the YNAB API endpoint /budgets/{budget_id}/payees and returns the payees list.
async def get_payees(self, budget_id: str) -> List[Dict[str, Any]]: """Get all payees for a budget.""" response = await self._request("GET", f"/budgets/{budget_id}/payees") return response["data"]["payees"]