list_branches
List all branches of a GitHub repository by providing the owner and repository name. Supports pagination to control the number of results per page.
Instructions
List branches in a GitHub repository
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| owner | Yes | Repository owner | |
| repo | Yes | Repository name | |
| per_page | No | Results per page (default 10, max 100) | |
| page | No | Page number (default 1) |
Implementation Reference
- src/tools/repositories.ts:336-404 (registration)The tool 'list_branches' is registered via server.tool() call with description, Zod schema for inputs, and async handler callback.
server.tool( "list_branches", "List branches in a GitHub repository", { owner: z.string().describe("Repository owner"), repo: z.string().describe("Repository name"), per_page: z .number() .optional() .default(10) .describe("Results per page (default 10, max 100)"), page: z .number() .optional() .default(1) .describe("Page number (default 1)"), }, async ({ owner, repo, per_page, page }) => { try { const response = await octokit.rest.repos.listBranches({ owner, repo, per_page, page, }) const branches = response.data if (branches.length === 0) { return { content: [{ type: "text", text: "No branches found." }], } } // Get default branch const repoResponse = await octokit.rest.repos.get({ owner, repo }) const defaultBranch = repoResponse.data.default_branch // Format as clean markdown let markdown = `# Branches for ${owner}/${repo}\n\n` markdown += `Showing ${branches.length} branch(es) - Page ${page}\n` if (branches.length === per_page) { markdown += `*Note: More branches may be available. Use 'page' parameter to see next page.*\n` } markdown += `\n` branches.forEach(branch => { const isDefault = branch.name === defaultBranch markdown += `## ${branch.name}${isDefault ? " (default)" : ""}\n\n` markdown += `- **SHA:** ${branch.commit.sha.substring(0, 7)}\n` if (branch.protected) { markdown += `- **Protected:** Yes\n` } markdown += `- **URL:** ${branch.commit.url.replace("api.github.com/repos", "github.com").replace("/commits/", "/tree/")}\n` markdown += `\n` }) return { content: [{ type: "text", text: markdown }], } } catch (e: any) { return { content: [{ type: "text", text: `Error: ${e.message}` }], } } }, ) - src/tools/repositories.ts:353-403 (handler)Async handler function that calls octokit.rest.repos.listBranches to fetch branches, retrieves the default branch via octokit.rest.repos.get, and formats output as markdown.
async ({ owner, repo, per_page, page }) => { try { const response = await octokit.rest.repos.listBranches({ owner, repo, per_page, page, }) const branches = response.data if (branches.length === 0) { return { content: [{ type: "text", text: "No branches found." }], } } // Get default branch const repoResponse = await octokit.rest.repos.get({ owner, repo }) const defaultBranch = repoResponse.data.default_branch // Format as clean markdown let markdown = `# Branches for ${owner}/${repo}\n\n` markdown += `Showing ${branches.length} branch(es) - Page ${page}\n` if (branches.length === per_page) { markdown += `*Note: More branches may be available. Use 'page' parameter to see next page.*\n` } markdown += `\n` branches.forEach(branch => { const isDefault = branch.name === defaultBranch markdown += `## ${branch.name}${isDefault ? " (default)" : ""}\n\n` markdown += `- **SHA:** ${branch.commit.sha.substring(0, 7)}\n` if (branch.protected) { markdown += `- **Protected:** Yes\n` } markdown += `- **URL:** ${branch.commit.url.replace("api.github.com/repos", "github.com").replace("/commits/", "/tree/")}\n` markdown += `\n` }) return { content: [{ type: "text", text: markdown }], } } catch (e: any) { return { content: [{ type: "text", text: `Error: ${e.message}` }], } } }, - src/tools/repositories.ts:339-352 (schema)Zod schema defining input parameters: owner (string), repo (string), per_page (optional number, default 10), page (optional number, default 1).
{ owner: z.string().describe("Repository owner"), repo: z.string().describe("Repository name"), per_page: z .number() .optional() .default(10) .describe("Results per page (default 10, max 100)"), page: z .number() .optional() .default(1) .describe("Page number (default 1)"), },