gitlab_list_groups
List accessible GitLab groups with IDs, names, paths, and descriptions. Supports pagination, filtering by ownership, and name search for efficient group navigation and management.
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 |
|---|---|---|---|
| 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 | |
| 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 groups |
Implementation Reference
- src/mcp_gitlab/tool_handlers.py:591-599 (handler)The handler function that executes the core logic of the gitlab_list_groups tool. It extracts parameters from arguments, handles defaults, and delegates to the GitLabClient.list_groups method.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)
- src/mcp_gitlab/tool_handlers.py:1016-1017 (registration)The TOOL_HANDLERS dictionary maps the tool name TOOL_LIST_GROUPS to its handler function handle_list_groups. This mapping is used by the server.call_tool() method in server.py to dispatch tool calls.TOOL_LIST_GROUPS: handle_list_groups, TOOL_LIST_GROUP_PROJECTS: handle_list_group_projects,
- Pydantic/MCP schema definition for the gitlab_list_groups tool, including input validation, parameter descriptions, defaults, and constraints.types.Tool( 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 of the tool name string used throughout the codebase for consistency.TOOL_LIST_GROUPS = "gitlab_list_groups"
- src/mcp_gitlab/server.py:224-235 (schema)Duplicate inline schema definition used by the server's list_tools() handler for MCP protocol compliance.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} } } ),