gitlab_list_merge_requests
Retrieve and filter merge requests from a GitLab project to review active changes, track progress, or find specific submissions using state-based filtering and pagination.
Instructions
List project merge requests Returns: Array of MRs with key information Use when: Reviewing MRs, finding specific MRs Filtering: By state (opened/closed/merged/all) Pagination: Yes (default 20 per page)
Example response: [{ "iid": 456, "title": "Add new feature", "state": "opened", "source_branch": "feature/new-feature", "target_branch": "main", "draft": false, "has_conflicts": false, "web_url": "https://gitlab.com/group/project/-/merge_requests/456" }]
Related tools:
gitlab_get_merge_request: Full MR details
gitlab_get_merge_request_changes: View diffs
gitlab_merge_merge_request: Merge an MR
Input 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 | Merge request state filter Type: string (enum) Options: 'opened' | 'closed' | 'merged' | 'all' Default: 'all' Examples: - 'opened' (active MRs needing review) - 'merged' (completed MRs) - 'closed' (abandoned MRs) - 'all' (everything) Use case: Focus on MRs needing attention | 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:132-140 (handler)The main handler function that executes the tool logic: lists merge requests for a project by detecting or requiring project_id, then calling GitLabClient.get_merge_requests with state, pagination.
def handle_list_merge_requests(client: GitLabClient, arguments: Optional[Dict[str, Any]]) -> Dict[str, Any]: """Handle listing merge requests""" 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_merge_requests(project_id, state, per_page, page) - Input schema definition for the tool, specifying parameters project_id, state (default 'opened'), per_page, page with types, descriptions, enums, defaults, and constraints.
types.Tool( name=TOOL_LIST_MRS, description=desc.DESC_LIST_MRS, inputSchema={ "type": "object", "properties": { "project_id": {"type": "string", "description": desc.DESC_PROJECT_ID}, "state": {"type": "string", "description": desc.DESC_STATE_MR, "enum": ["opened", "closed", "merged", "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:1006-1006 (registration)Registration of the tool name to its handler function in the TOOL_HANDLERS dictionary, which is used by server.py.handle_call_tool to dispatch tool calls.
TOOL_LIST_MRS: handle_list_merge_requests, - src/mcp_gitlab/constants.py:181-181 (helper)Constant defining the canonical tool name string used throughout the codebase for consistency.
TOOL_LIST_MRS = "gitlab_list_merge_requests"