GitLab MCP Server

Instructions

Implementation Reference

• src/server.ts:237-241 (handler)

  The tool handler in server.ts that receives the request and calls the api.searchProjects function.

  case "search_repositories": {
    const args = SearchRepositoriesSchema.parse(request.params.arguments);
    const results = await api.searchProjects(args.search, args.page, args.per_page);
    return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
  }

• src/api/projects.ts:7-30 (handler)

  The actual implementation of searching projects in the API layer.

  export async function searchProjects(query: string, page: number = 1, perPage: number = 20): Promise<GitLabSearchResponse> {
    if (!query?.trim()) {
      throw new Error("Search query is required");
    }
    if (page < 1) {
      throw new Error("Page number must be 1 or greater");
    }
    if (perPage < 1 || perPage > 100) {
      throw new Error("Per page must be between 1 and 100");
    }
  
    const params = buildSearchParams({
      search: query,
      page: page.toString(),
      per_page: perPage.toString()
    });
  
    const projects = await gitlabGet<GitLabRepository[]>("/projects", params);
  
    return GitLabSearchResponseSchema.parse({
      count: projects.length, // GitLab doesn't always provide total in headers
      items: projects
    });
  }

• src/schemas.ts:221-229 (schema)

  The schema definition for the search_repositories tool inputs.

  export const SearchRepositoriesSchema = z.object({
    search: z.string().describe("Search query"), // Changed from query to match GitLab API
    page: z.number().optional().describe("Page number for pagination (default: 1)"),
    per_page: z.number().optional().describe("Number of results per page (default: 20)")
  });
  
  export const SearchGroupsSchema = z.object({
    search: z.string().describe("Search query for groups"),
    page: z.number().optional().describe("Page number for pagination (default: 1)"),

• src/server.ts:64-68 (registration)

  Tool registration in the server list_tools response.

  {
    name: "search_repositories",
    description: "Search for GitLab projects",
    inputSchema: zodToJsonSchema(SearchRepositoriesSchema)
  },