GitLab MCP Server

Instructions

Implementation Reference

• src/api/groups.ts:5-26 (handler)

  The actual implementation of the 'searchGroups' function which queries the GitLab API.

  export async function searchGroups(
    query: string,
    page: number = 1,
    perPage: number = 20,
    owned?: boolean,
    minAccessLevel?: number
  ): Promise<GitLabGroupSearchResponse> {
    const params = buildSearchParams({
      search: query,
      page: page.toString(),
      per_page: perPage.toString(),
      ...(owned !== undefined && { owned: owned.toString() }),
      ...(minAccessLevel !== undefined && { min_access_level: minAccessLevel.toString() })
    });
  
    const groups = await gitlabGet<any[]>("/groups", params);
  
    return GitLabGroupSearchResponseSchema.parse({
      count: groups.length,
      items: groups
    });
  }

• src/server.ts:243-247 (registration)

  Tool handler registration for 'search_groups' which parses arguments and calls the API function.

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

• src/server.ts:69-73 (registration)

  Declaration of the 'search_groups' tool in the MCP server capabilities.

  {
    name: "search_groups",
    description: "Search for GitLab groups",
    inputSchema: zodToJsonSchema(SearchGroupsSchema)
  },

• src/schemas.ts:227-237 (schema)

  Zod schema definition for input validation of the search_groups tool.

  export const SearchGroupsSchema = z.object({
    search: z.string().describe("Search query for groups"),
    page: z.number().optional().describe("Page number for pagination (default: 1)"),
    per_page: z.number().optional().describe("Number of results per page (default: 20)"),
    owned: z.boolean().optional().describe("Limit by groups owned by the current user"),
    min_access_level: z
      .number()
      .optional()
      .describe("Limit by minimum access level (10=Guest, 20=Reporter, 30=Developer, 40=Maintainer, 50=Owner)")
  });