GitLab MCP Server

Instructions

Implementation Reference

• src/handlers/repository.ts:12-32 (handler)

  The main handler function that executes the logic for listing project branches by calling the GitLab API and returning the JSON response.

  async listProjectBranches(args: ListProjectBranchesParams) {
    const params = new URLSearchParams();
  
    if (args.search) params.append("search", args.search);
    params.append("per_page", String(args.per_page || 20));
  
    const data = await this.client.get(
      `/projects/${encodeURIComponent(
        args.project_id
      )}/repository/branches?${params.toString()}`
    );
  
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(data, null, 2),
        },
      ],
    };
  }

• src/types.ts:314-318 (schema)

  TypeScript interface defining the input parameters for the list_project_branches tool.

  export interface ListProjectBranchesParams {
    project_id: string;
    search?: string;
    per_page?: number;
  }

• src/tools/repository.ts:4-27 (registration)

  Tool registration definition including name, description, and input JSON schema.

  {
    name: "list_project_branches",
    description: "List branches in a project",
    inputSchema: {
      type: "object",
      properties: {
        project_id: {
          type: "string",
          description: "Project ID or path",
        },
        search: {
          type: "string",
          description: "Search branches by name",
        },
        per_page: {
          type: "number",
          description: "Number of results per page (max 100)",
          maximum: 100,
          default: 20,
        },
      },
      required: ["project_id"],
    },
  },

• src/server.ts:269-272 (registration)

  Dispatch logic in the main server that routes calls to the repository handler.

  case "list_project_branches":
    return await this.repositoryHandlers.listProjectBranches(
      args as unknown as ListProjectBranchesParams
    );