gitlab_list_group_projects
Retrieve a list of projects within a specific GitLab group, including optional search, pagination, and subgroup inclusion. Simplify group hierarchy navigation and project discovery.
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 | Default |
|---|---|---|---|
| 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) | |
| 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 | |
| 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 | |
| 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 | |
| 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 |
Implementation Reference
- src/mcp_gitlab/tool_handlers.py:609-623 (handler)The handler function that executes the gitlab_list_group_projects tool. It extracts arguments, validates required group_id, and delegates to GitLabClient.list_group_projects.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 )
- The tool schema definition including name, description, and inputSchema for validation of gitlab_list_group_projects parameters.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, mapping tool name to its execution handler.TOOL_LIST_GROUP_PROJECTS: handle_list_group_projects,
- src/mcp_gitlab/constants.py:202-202 (helper)Constant definition for the tool name 'gitlab_list_group_projects' used across modules.TOOL_LIST_GROUP_PROJECTS = "gitlab_list_group_projects"