You Need A Budget (YNAB) MCP

Instructions

Implementation Reference

• src/ynab_mcp_server/server.py:305-321 (handler)

  The handler function within handle_call_tool that executes the 'manage-payees' tool logic. It validates the input using ManagePayeesInput, determines the budget ID, and calls ynab_client.update_payees for the 'rename' action.

  elif name == "manage-payees":
      args = ManagePayeesInput.model_validate(arguments or {})
      budget_id = await _get_budget_id(args.model_dump())
  
      if args.action == "rename":
          await ynab_client.update_payees(
              budget_id=budget_id,
              payee_ids=args.payee_ids,
              name=args.name,
          )
          return [
              types.TextContent(
                  type="text",
                  text=f"Successfully renamed {len(args.payee_ids)} payees to '{args.name}'.",
              )
          ]
  elif name == "manage-budgeted-amount":

• src/ynab_mcp_server/tool_models.py:74-91 (schema)

  Pydantic model defining the input schema and validation for the 'manage-payees' tool, including action, payee_ids, and name fields.

  class ManagePayeesInput(BudgetIdInput):
      action: ManagePayeesAction = Field(..., description="The action to perform.")
      payee_ids: List[str] = Field(..., description="The IDs of the payees to affect.")
      name: Optional[str] = Field(None, description="The new name for the payees. Required for 'rename' action.")
  
      @model_validator(mode='before')
      @classmethod
      def check_fields_for_action(cls, values):
          action = values.get('action')
          if not action:
              raise ValueError("'action' is a required field.")
  
          if action == 'rename':
              if not values.get('name'):
                  raise ValueError("'name' is required for the 'rename' action.")
          
          return values 

• src/ynab_mcp_server/server.py:77-81 (registration)

  Registration of the 'manage-payees' tool in the handle_list_tools function, specifying name, description, and input schema.

  types.Tool(
      name="manage-payees",
      description="Merge multiple payee names into a single name. Use this to clean up payee data, for example, by renaming 'STARBUCKS #123' and 'Starbucks Coffee' to just 'Starbucks'.",
      inputSchema=ManagePayeesInput.model_json_schema(),
  ),

• src/ynab_mcp_server/ynab_client.py:305-309 (helper)

  Helper method in YNABClient that performs the actual payee renaming by concurrently updating each payee using update_payee.

  async def update_payees(self, budget_id: str, payee_ids: list[str], name: str):
      """Updates multiple payees to the same name."""
      tasks = [self.update_payee(budget_id, payee_id, name) for payee_id in payee_ids]
      await asyncio.gather(*tasks)