list_merge_requests

Retrieve and filter merge requests from a GitLab project using criteria like state, branch, assignee, or search terms to manage code review workflows.

Instructions

List merge requests in a project

Input Schema

TableJSON Schema

Name	Required	Description	Default
`project_id`	Yes	Project ID or path
`state`	No	Filter by merge request state	opened
`target_branch`	No	Filter by target branch
`source_branch`	No	Filter by source branch
`assignee_id`	No	Filter by assignee user ID
`author_id`	No	Filter by author user ID
`reviewer_id`	No	Filter by reviewer user ID
`reviewer_username`	No	Filter by reviewer username
`search`	No	Search merge requests by title and description
`scope`	No	Return merge requests with the given scope (optional)
`per_page`	No	Number of results per page (max 100)

Implementation Reference

src/handlers/merge-requests.ts:78-110 (handler)

The core handler function that executes the list_merge_requests tool logic. It constructs URL search parameters from input args and fetches the list of merge requests from the GitLab API, returning the JSON-formatted response.

async listMergeRequests(args: ListMergeRequestsParams) {
  const params = new URLSearchParams();

  if (args.state) params.append("state", args.state);
  if (args.target_branch) params.append("target_branch", args.target_branch);
  if (args.source_branch) params.append("source_branch", args.source_branch);
  if (args.assignee_id)
    params.append("assignee_id", String(args.assignee_id));
  if (args.author_id) params.append("author_id", String(args.author_id));
  if (args.reviewer_id)
    params.append("reviewer_id", String(args.reviewer_id));
  if (args.reviewer_username)
    params.append("reviewer_username", args.reviewer_username);
  if (args.search) params.append("search", args.search);
  // Only add scope if explicitly provided by user
  if (args.scope) params.append("scope", args.scope);
  params.append("per_page", String(args.per_page || 20));

  const data = await this.client.get(
    `/projects/${encodeURIComponent(
      args.project_id
    )}/merge_requests?${params.toString()}`
  );

  return {
    content: [
      {
        type: "text",
        text: JSON.stringify(data, null, 2),
      },
    ],
  };
}

src/tools/merge-requests.ts:4-62 (schema)

The MCP tool definition for 'list_merge_requests' including name, description, and detailed inputSchema used for validation.

{
  name: 'list_merge_requests',
  description: 'List merge requests in a project',
  inputSchema: {
    type: 'object',
    properties: {
      project_id: {
        type: 'string',
        description: 'Project ID or path',
      },
      state: {
        type: 'string',
        enum: ['opened', 'closed', 'merged', 'all'],
        description: 'Filter by merge request state',
        default: 'opened',
      },
      target_branch: {
        type: 'string',
        description: 'Filter by target branch',
      },
      source_branch: {
        type: 'string',
        description: 'Filter by source branch',
      },
      assignee_id: {
        type: 'number',
        description: 'Filter by assignee user ID',
      },
      author_id: {
        type: 'number',
        description: 'Filter by author user ID',
      },
      reviewer_id: {
        type: 'number',
        description: 'Filter by reviewer user ID',
      },
      reviewer_username: {
        type: 'string',
        description: 'Filter by reviewer username',
      },
      search: {
        type: 'string',
        description: 'Search merge requests by title and description',
      },
      scope: {
        type: 'string',
        enum: ['created_by_me', 'assigned_to_me', 'all'],
        description: 'Return merge requests with the given scope (optional)',
      },
      per_page: {
        type: 'number',
        description: 'Number of results per page (max 100)',
        maximum: 100,
        default: 20,
      },
    },
    required: ['project_id'],
  },
},

src/server.ts:177-180 (registration)
The dispatch case in the server's CallToolRequest handler that routes calls to the list_merge_requests tool to the appropriate handler method.
```
case "list_merge_requests":
  return await this.mergeRequestHandlers.listMergeRequests(
    args as unknown as ListMergeRequestsParams
  );
```

src/types.ts:240-252 (schema)

TypeScript interface defining the input parameters for listMergeRequests, matching the tool's inputSchema.

export interface ListMergeRequestsParams {
  project_id: string;
  state?: 'opened' | 'closed' | 'merged' | 'all';
  target_branch?: string;
  source_branch?: string;
  assignee_id?: number;
  author_id?: number;
  reviewer_id?: number;
  reviewer_username?: string;
  search?: string;
  scope?: 'created_by_me' | 'assigned_to_me' | 'all';
  per_page?: number;
}

src/server.ts:116-116 (registration)
Instantiation of the MergeRequestHandlers class instance used to handle list_merge_requests and other MR tools.
```
this.mergeRequestHandlers = new MergeRequestHandlers(this.client);
```

GitLab MCP Server