gitlab_list_groups
List accessible GitLab groups to browse group hierarchy, find group IDs, and filter by ownership or search terms.
Instructions
List accessible GitLab groups Returns: Array of groups with ID, name, path, description Use when: Browsing groups, finding group IDs, navigating group hierarchy Pagination: Yes (default 50 per page) Filtering: By ownership, name search
Example response: [{ "id": 123, "name": "My Group", "path": "my-group", "full_path": "parent-group/my-group", "description": "Group for team projects", "web_url": "https://gitlab.com/groups/my-group", "visibility": "private" }]
Related tools:
gitlab_get_group: Get full group details
gitlab_list_group_projects: List projects in a group
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| 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 groups | |
| owned | No | Filter for owned groups only Type: boolean Default: false Options: - true: Only groups where you are the owner - false: All accessible groups Use case: Managing your own groups | |
| 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:591-599 (handler)The primary handler function that implements the core logic for the 'gitlab_list_groups' tool. It parses input arguments and calls the underlying GitLabClient.list_groups method to fetch groups.
def handle_list_groups(client: GitLabClient, arguments: Optional[Dict[str, Any]]) -> Dict[str, Any]: """Handle listing groups""" search = get_argument(arguments, "search") owned = get_argument(arguments, "owned", False) per_page = get_argument(arguments, "per_page", DEFAULT_PAGE_SIZE) page = get_argument(arguments, "page", 1) return client.list_groups(search=search, owned=owned, per_page=per_page, page=page) - The input schema definition for the 'gitlab_list_groups' tool, specifying parameters like search, owned, per_page, and page.
name=TOOL_LIST_GROUPS, description=desc.DESC_LIST_GROUPS, inputSchema={ "type": "object", "properties": { "search": {"type": "string", "description": desc.DESC_SEARCH_TERM + " for groups"}, "owned": {"type": "boolean", "description": desc.DESC_OWNED_GROUPS, "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} } } ), - src/mcp_gitlab/tool_handlers.py:1016-1017 (registration)Registration of the handler function in the TOOL_HANDLERS dictionary, which maps tool names to their handler functions. Used by server.py to dispatch calls.
TOOL_LIST_GROUPS: handle_list_groups, TOOL_LIST_GROUP_PROJECTS: handle_list_group_projects, - src/mcp_gitlab/server.py:224-235 (registration)Tool registration and schema in the server's list_tools handler, exposing the tool to MCP clients.
name=TOOL_LIST_GROUPS, description=desc.DESC_LIST_GROUPS, inputSchema={ "type": "object", "properties": { "search": {"type": "string", "description": desc.DESC_SEARCH_TERM + " for groups"}, "owned": {"type": "boolean", "description": desc.DESC_OWNED_GROUPS, "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} } } ), - src/mcp_gitlab/constants.py:200-200 (helper)Constant definition for the tool name 'gitlab_list_groups', used across modules for consistency.
TOOL_LIST_GROUPS = "gitlab_list_groups"