list_apps
List and filter Heroku applications by ownership, collaboration, team, or private space. View app names, regions, and ownership details in JSON or text format for easy management.
Instructions
List Heroku applications with flexible filtering options. Use this tool when you need to: 1) Show all apps owned by the user, 2) Show apps where the user is a collaborator (use all=true), 3) Filter apps by team or private space. Note: For checking app name availability, prefer using get_app_info as it returns a more focused dataset. The response includes app names, regions, and ownership information.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| all | No | When true, displays a comprehensive list including: (1) apps owned by the user and (2) apps where the user is a collaborator through direct access or team membership. When false or omitted, shows only owned apps. | |
| json | No | Controls the output format. When true, returns a detailed JSON response containing app metadata such as generation, buildpacks, owner information, and region. When false or omitted, returns a simplified text format. | |
| personal | No | Forces the tool to list applications from your personal account, even when you have a default team configured. When true, overrides any default team setting and shows only apps owned by your personal account. This is particularly useful when you work with multiple teams but need to specifically view your personal apps. When false or omitted, follows the default behavior of using the default team if one is set. | |
| space | No | Filters the results to show only apps within a specific private space. Provide the private space name to filter. This parameter is mutually exclusive with the team parameter. | |
| team | No | Filters the results to show only apps belonging to a specific team. Provide the team name to filter. This parameter is mutually exclusive with the space parameter. |
Implementation Reference
- src/tools/apps.ts:36-48 (handler)The handler function for the 'list_apps' tool. It constructs a Heroku CLI 'apps' command using CommandBuilder with provided options (all, personal, space, team), executes it via herokuRepl, and processes the output with handleCliOutput.
async (options: ListAppsOptions): Promise<McpToolResponse> => { const command = new CommandBuilder(TOOL_COMMAND_MAP.LIST_APPS) .addFlags({ all: options.all, personal: options.personal, space: options.space, team: options.team }) .build(); const output = await herokuRepl.executeCommand(command); return handleCliOutput(output); } - src/tools/apps.ts:13-18 (schema)Zod schema defining the input parameters for the list_apps tool: optional flags for filtering apps by ownership, personal/team, space, or team.
export const listAppsOptionsSchema = z.object({ all: z.boolean().optional().describe('Show owned apps and collaborator access. Default: owned only'), personal: z.boolean().optional().describe('List personal account apps only, ignoring default team'), space: z.string().optional().describe('Filter by private space name. Excludes team param'), team: z.string().optional().describe('Filter by team name. Excludes space param') }); - src/tools/apps.ts:31-50 (registration)The registerListAppsTool function that registers the 'list_apps' tool on the MCP server, providing name, description, schema, and handler.
export const registerListAppsTool = (server: McpServer, herokuRepl: HerokuREPL): void => { server.tool( 'list_apps', 'List Heroku apps: owned, collaborator access, team/space filtering', listAppsOptionsSchema.shape, async (options: ListAppsOptions): Promise<McpToolResponse> => { const command = new CommandBuilder(TOOL_COMMAND_MAP.LIST_APPS) .addFlags({ all: options.all, personal: options.personal, space: options.space, team: options.team }) .build(); const output = await herokuRepl.executeCommand(command); return handleCliOutput(output); } ); }; - src/index.ts:50-50 (registration)Invocation of registerListAppsTool in the main index.ts to register the list_apps tool during server setup.
apps.registerListAppsTool(server, herokuRepl); - src/utils/tool-commands.ts:7-7 (helper)TOOL_COMMAND_MAP constant mapping LIST_APPS to the Heroku CLI command 'apps', used by the handler.
LIST_APPS: 'apps',