gitlab_list_issues
List project issues from GitLab to browse work items, filter by state (opened/closed/all), and view details like title, labels, assignees, and status with pagination support.
Instructions
List project issues Returns: Array of issues with details Use when: Browsing issues, finding work items Filtering: By state (opened/closed/all) Pagination: Yes (default 20 per page)
Example response: [{ "iid": 123, "title": "Fix login bug", "state": "opened", "labels": ["bug", "high-priority"], "assignees": [{"username": "johndoe"}], "web_url": "https://gitlab.com/group/project/-/issues/123" }]
Related tools:
gitlab_get_issue: Get full issue details
gitlab_add_issue_comment: Comment on issue
gitlab_search_in_project: Search issue content
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | No | Project identifier (auto-detected if not provided) Type: integer OR string Format: numeric ID or 'namespace/project' Optional: Yes - auto-detects from current git repository Examples: - 12345 (numeric ID) - 'gitlab-org/gitlab' (namespace/project path) - 'my-group/my-subgroup/my-project' (nested groups) Note: If in a git repo with GitLab remote, this can be omitted | |
| state | No | Issue state filter Type: string (enum) Options: 'opened' | 'closed' | 'all' Default: 'all' Examples: - 'opened' (only open issues) - 'closed' (only closed issues) - 'all' (both open and closed) Use case: Filter to see only active work items | opened |
| 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:113-121 (handler)The main handler function that implements the gitlab_list_issues tool logic. It resolves the project ID (auto-detecting from git if not provided), extracts pagination and state parameters, and calls the GitLab client's get_issues method.
def handle_list_issues(client: GitLabClient, arguments: Optional[Dict[str, Any]]) -> Dict[str, Any]: """Handle listing issues""" project_id = require_project_id(client, arguments) state = get_argument(arguments, "state", "opened") per_page = get_argument(arguments, "per_page", DEFAULT_PAGE_SIZE) page = get_argument(arguments, "page", 1) return client.get_issues(project_id, state, per_page, page) - Pydantic/MCP schema definition for the gitlab_list_issues tool, including input parameters (project_id, state, per_page, page) with descriptions, types, enums, defaults, and constraints.
name=TOOL_LIST_ISSUES, description=desc.DESC_LIST_ISSUES, inputSchema={ "type": "object", "properties": { "project_id": {"type": "string", "description": desc.DESC_PROJECT_ID}, "state": {"type": "string", "description": desc.DESC_STATE_ISSUE, "enum": ["opened", "closed", "all"], "default": "opened"}, "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:1005-1006 (registration)Registration of the gitlab_list_issues tool in the TOOL_HANDLERS dictionary, mapping the tool name (TOOL_LIST_ISSUES) to its handler function handle_list_issues.
TOOL_LIST_ISSUES: handle_list_issues, TOOL_LIST_MRS: handle_list_merge_requests, - src/mcp_gitlab/constants.py:179-179 (helper)Constant definition for the tool name 'gitlab_list_issues', used consistently across handler registration, schema definitions, and tests.
TOOL_LIST_ISSUES = "gitlab_list_issues" - Helper function used by the handler to resolve project_id either from arguments or by auto-detecting from the current git repository.
def require_project_id(client: GitLabClient, arguments: Optional[Dict[str, Any]]) -> str: """Get project_id or raise error if not found""" project_id = get_project_id_or_detect(client, arguments) if not project_id: raise ValueError(ERROR_NO_PROJECT) return project_id