gitlab_list_group_projects

List and search projects within a GitLab group, optionally including subgroups, to browse and find projects in group hierarchies.

Instructions

List projects within a group Returns: Array of projects belonging to the specified group Use when: Browsing group projects, finding projects in group hierarchy Pagination: Yes (default 50 per page) Options: Include subgroup projects with include_subgroups=true

Example response: [{ "id": 456, "name": "project-one", "path_with_namespace": "my-group/project-one", "description": "First project in group", "web_url": "https://gitlab.com/my-group/project-one" }]

Related tools:

gitlab_get_group: Get group details
gitlab_get_project: Get full project details

Input Schema

TableJSON Schema

Name	Required	Description
`group_id`	Yes	Group identifier Type: integer OR string Format: numeric ID or 'group/subgroup' path Required: Yes Examples: - 456 (numeric ID) - 'my-group' (group path) - 'parent-group/sub-group' (nested group path)
`search`	No	Search query Type: string Matching: Case-insensitive, partial matching Searches in: Project names and descriptions Examples: - 'frontend' (finds 'frontend-app', 'old-frontend', etc.) - 'API' (matches 'api', 'API', 'GraphQL-API', etc.) Tip: Use specific terms for better results for projects
`include_subgroups`	No	Include projects from subgroups Type: boolean Default: false Options: - true: Include all descendant group projects - false: Only direct group projects Use case: Navigating hierarchical group structures
`per_page`	No	Number of results per page Type: integer Range: 1-100 Default: 20 Example: 50 (for faster browsing) Tip: Use smaller values (10-20) for detailed operations, larger (50-100) for listing
`page`	No	Page number for pagination Type: integer Range: ≥1 Default: 1 Example: 3 (to get the third page of results) Note: Use with per_page to navigate large result sets

Implementation Reference

src/mcp_gitlab/tool_handlers.py:609-623 (handler)

Handler function that extracts parameters from arguments and delegates to GitLabClient.list_group_projects to list projects in a group.

def handle_list_group_projects(client: GitLabClient, arguments: Optional[Dict[str, Any]]) -> Dict[str, Any]:
    """Handle listing projects within a group"""
    group_id = require_argument(arguments, "group_id")
    search = get_argument(arguments, "search")
    include_subgroups = get_argument(arguments, "include_subgroups", False)
    per_page = get_argument(arguments, "per_page", DEFAULT_PAGE_SIZE)
    page = get_argument(arguments, "page", 1)
    
    return client.list_group_projects(
        group_id, 
        search=search, 
        include_subgroups=include_subgroups,
        per_page=per_page, 
        page=page
    )

src/mcp_gitlab/tool_definitions.py:109-123 (schema)

Pydantic/MCP input schema definition for the gitlab_list_group_projects tool, specifying parameters like group_id (required), search, include_subgroups, pagination.

types.Tool(
    name=TOOL_LIST_GROUP_PROJECTS,
    description=desc.DESC_LIST_GROUP_PROJECTS,
    inputSchema={
        "type": "object",
        "properties": {
            "group_id": {"type": "string", "description": desc.DESC_GROUP_ID},
            "search": {"type": "string", "description": desc.DESC_SEARCH_TERM + " for projects"},
            "include_subgroups": {"type": "boolean", "description": desc.DESC_INCLUDE_SUBGROUPS, "default": False},
            "per_page": {"type": "integer", "description": desc.DESC_PER_PAGE, "default": DEFAULT_PAGE_SIZE, "minimum": 1, "maximum": MAX_PAGE_SIZE},
            "page": {"type": "integer", "description": desc.DESC_PAGE_NUMBER, "default": 1, "minimum": 1}
        },
        "required": ["group_id"]
    }
),

src/mcp_gitlab/tool_handlers.py:1017-1017 (registration)
Registration of the handler function in the TOOL_HANDLERS dictionary used by server.call_tool() to dispatch tool calls.
```
TOOL_LIST_GROUP_PROJECTS: handle_list_group_projects,
```

src/mcp_gitlab/server.py:1251-1294 (registration)

Dispatch logic in @server.call_tool() that looks up the handler from TOOL_HANDLERS dict and executes it with GitLab client and arguments.

    handler = TOOL_HANDLERS.get(name)
    if not handler:
        raise ValueError(f"Unknown tool: {name}")
    
    # Execute the handler
    result = handler(client, arguments)
    
    # Truncate response if too large
    result = truncate_response(result, MAX_RESPONSE_SIZE)
    
    return [types.TextContent(
        type="text",
        text=json.dumps(result, indent=2)
    )]
    
except gitlab.exceptions.GitlabAuthenticationError as e:
    logger.error(f"Authentication failed: {e}")
    error_response = sanitize_error(e, ERROR_AUTH_FAILED)
    return [types.TextContent(type="text", text=json.dumps(error_response, indent=2))]
except gitlab.exceptions.GitlabGetError as e:
    response_code = getattr(e, 'response_code', None)
    if response_code == 404:
        logger.warning(f"Resource not found: {e}")
        error_response = sanitize_error(e, ERROR_NOT_FOUND)
    elif response_code == 429:
        logger.warning(f"Rate limit exceeded: {e}")
        error_response = sanitize_error(e, ERROR_RATE_LIMIT)
    else:
        logger.error(f"GitLab API error: {e}")
        error_response = sanitize_error(e)
    return [types.TextContent(type="text", text=json.dumps(error_response, indent=2))]
except gitlab.exceptions.GitlabError as e:
    logger.error(f"General GitLab error: {e}")
    error_response = sanitize_error(e)
    return [types.TextContent(type="text", text=json.dumps(error_response, indent=2))]
except ValueError as e:
    logger.warning(f"Invalid input: {e}")
    error_response = sanitize_error(e, ERROR_INVALID_INPUT)
    return [types.TextContent(type="text", text=json.dumps(error_response, indent=2))]
except Exception as e:
    logger.error(f"Unexpected error: {e}")
    error_response = sanitize_error(e, ERROR_GENERIC)
    return [types.TextContent(type="text", text=json.dumps(error_response, indent=2))]

src/mcp_gitlab/constants.py:202-202 (helper)
Constant defining the exact tool name string 'gitlab_list_group_projects' used across handler mapping, schema, and server.
```
TOOL_LIST_GROUP_PROJECTS = "gitlab_list_group_projects"
```

MCP GitLab Server