gitlab_list_projects
Browse and filter accessible GitLab projects by ownership or search terms, returning summaries with IDs, names, and URLs for easy project discovery.
Instructions
List accessible GitLab projects Returns: Array of project summaries with ID, name, description, URL Use when: Browsing projects, finding project IDs Pagination: Yes (default 20 per page) Filtering: By ownership, name search
Example response: [{ "id": 12345, "name": "my-project", "path_with_namespace": "group/my-project", "description": "Project description", "web_url": "https://gitlab.com/group/my-project" }]
Related tools:
gitlab_get_project: Get full project details
gitlab_search_projects: Search all GitLab projects
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| owned | No | Filter for owned projects only Type: boolean Default: false Options: - true: Only projects where you are the owner - false: All accessible projects Use case: Quickly find your personal projects | |
| 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 | |
| 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:84-92 (handler)Core implementation of the gitlab_list_projects tool. Extracts pagination and filter parameters from arguments and calls GitLabClient.get_projects() to fetch the list of projects.def handle_list_projects(client: GitLabClient, arguments: Optional[Dict[str, Any]]) -> Dict[str, Any]: """Handle listing projects""" owned = get_argument(arguments, "owned", False) search = get_argument(arguments, "search") per_page = get_argument(arguments, "per_page", DEFAULT_PAGE_SIZE) page = get_argument(arguments, "page", 1) return client.get_projects(owned=owned, search=search, per_page=per_page, page=page)
- src/mcp_gitlab/server.py:166-178 (schema)MCP Tool schema definition exposed via list_tools(), including input validation schema, properties for owned/search/pagination, and description reference.types.Tool( name=TOOL_LIST_PROJECTS, description=desc.DESC_LIST_PROJECTS, inputSchema={ "type": "object", "properties": { "owned": {"type": "boolean", "description": desc.DESC_OWNED_PROJECTS, "default": False}, "search": {"type": "string", "description": desc.DESC_SEARCH_TERM + " for projects"}, "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:1003-1005 (registration)Mapping of tool name to handler function in TOOL_HANDLERS dictionary, used by server.call_tool() to dispatch executions.# List tools TOOL_LIST_PROJECTS: handle_list_projects, TOOL_LIST_ISSUES: handle_list_issues,
- src/mcp_gitlab/constants.py:177-177 (helper)Constant defining the canonical tool name string, used for registration, schemas, and references throughout the codebase.TOOL_LIST_PROJECTS = "gitlab_list_projects"
- Centralized tool schema definition in tool_definitions.TOOLS list (potentially for export/docs), matching server.py implementation.types.Tool( name=TOOL_LIST_PROJECTS, description=desc.DESC_LIST_PROJECTS, inputSchema={ "type": "object", "properties": { "owned": {"type": "boolean", "description": desc.DESC_OWNED_PROJECTS, "default": False}, "search": {"type": "string", "description": desc.DESC_SEARCH_TERM + " for projects"}, "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} } } ),