GitLab MCP server

With the GitLab Model Context Protocol (MCP) server, you can securely connect AI tools and applications to your GitLab instance. AI assistants like Claude Desktop, Claude Code, Cursor, and other MCP-compatible tools can then access your GitLab data and perform actions on your behalf.

The MCP server provides a standardized way for AI tools to:

• Access GitLab project information.
• Retrieve issue and merge request data.
• Interact with GitLab APIs securely.
• Perform GitLab-specific operations through AI assistants.

The GitLab MCP server supports OAuth 2.0 Dynamic Client Registration, which enables AI tools to register themselves with your GitLab instance. When an AI tool connects to your GitLab MCP server for the first time, it:

1. Registers itself as an OAuth application.
2. Requests authorization to access your GitLab data.
3. Receives an access token for secure API access.

For a click-through demo, see Duo Agent Platform - MCP server.

Prerequisites

To use the MCP server:

• Beta and experimental features must be turned on.

Connect Cursor to a GitLab MCP server

You can configure the GitLab MCP server in Cursor by using:

• HTTP transport (recommended): Direct connection without additional dependencies.
• stdio transport with mcp-remote: Connection through a proxy (requires Node.js).

HTTP transport (recommended)

To configure the GitLab MCP server in Cursor by using HTTP transport:

1. In Cursor, go to Settings > Cursor Settings > Tools & MCP.

2. Under Installed MCP Servers, select New MCP Server.

3. Add this definition to the mcpServers key in the opened mcp.json file:

   • Replace <gitlab.example.com> with:
     • On GitLab Self-Managed, your GitLab instance URL.
     • On GitLab.com, gitlab.com.
   {
     "mcpServers": {
       "GitLab": {
         "type": "http",
         "url": "https://<gitlab.example.com>/api/v4/mcp"
       }
     }
   }

4. Save the file and restart Cursor.

5. In Cursor, go to Settings > Cursor Settings > Tools & MCP.

6. Under Installed MCP Servers, find your GitLab server and select Connect.

7. In your browser, review and approve the authorization request.

You can now start a new chat and ask a question depending on the available tools.

stdio transport with mcp-remote

Prerequisites:

• Install Node.js version 20 or later.

To configure the GitLab MCP server in Cursor by using stdio transport:

1. In Cursor, go to Settings > Cursor Settings > Tools & MCP.

2. Under Installed MCP Servers, select New MCP Server.

3. Add this definition to the mcpServers key in the opened mcp.json file:

   • For the "command": parameter, if npx is installed locally instead of globally, provide the full path to npx.
   • Replace <gitlab.example.com> with:
     • On GitLab Self-Managed, your GitLab instance URL.
     • On GitLab.com, gitlab.com.
   {
     "mcpServers": {
       "GitLab": {
         "command": "npx",
         "args": [
           "mcp-remote",
           "https://<gitlab.example.com>/api/v4/mcp"
         ]
       }
     }
   }

   • The --static-oauth-client-metadata parameter is optional for the mcp-remote module to explicitly set the OAuth scope to mcp. If omitted, GitLab defaults to the mcp scope for dynamic applications.
   {
     "mcpServers": {
       "GitLab": {
         "command": "npx",
         "args": [
           "mcp-remote",
           "https://<gitlab.example.com>/api/v4/mcp",
           "--static-oauth-client-metadata",
           "{\"scope\": \"mcp\"}"
         ]
       }
     }
   }

4. Save the file, and wait for your browser to open the OAuth authorization page.

   If this does not happen, close and restart Cursor.

5. In your browser, review and approve the authorization request.

You can now start a new chat and ask a question depending on the available tools.

Connect Claude Code to a GitLab MCP server

Claude Code uses HTTP transport for direct connection without additional dependencies. To configure the GitLab MCP server in Claude Code:

1. In your terminal, add the MCP server with the CLI:

   • Replace <gitlab.example.com> with:
     • On GitLab Self-Managed, your GitLab instance URL.
     • On GitLab.com, gitlab.com.
   claude mcp add --transport http GitLab https://<gitlab.example.com>/api/v4/mcp

2. Start Claude Code:

   claude

3. Authenticate with the MCP server:

   • In the chat, type /mcp.
   • From the list, select your GitLab server.
   • In your browser, review and approve the authorization request.

4. Optional. To verify the connection, type /mcp again. Your GitLab server should appear as connected.

You can now start a new chat and ask a question depending on the available tools.

Connect Claude Desktop to a GitLab MCP server

Prerequisites:

• Install Node.js version 20 or later.
• Ensure Node.js is available globally in the PATH environment variable (which -a node).

To configure the GitLab MCP server in Claude Desktop:

1. Open Claude Desktop.

2. Edit the configuration file. You can do either of the following:

   • In Claude Desktop, go to Settings > Developer > Edit Config.
   • On macOS, open the ~/Library/Application Support/Claude/claude_desktop_config.json file.

3. Add this entry for the GitLab MCP server, editing as needed:

   • For the "command": parameter, if npx is installed locally instead of globally, provide the full path to npx.
   • Replace <gitlab.example.com> with:
     • On GitLab Self-Managed, your GitLab instance URL.
     • On GitLab.com, GitLab.com.
   {
     "mcpServers": {
       "GitLab": {
         "command": "npx",
         "args": [
           "-y",
           "mcp-remote",
           "https://<gitlab.example.com>/api/v4/mcp"
         ]
       }
     }
   }

   • The --static-oauth-client-metadata parameter is optional for the mcp-remote module to explicitly set the OAuth scope to mcp. If omitted, GitLab defaults to the mcp scope for dynamic applications.
   {
     "mcpServers": {
       "GitLab": {
         "command": "npx",
         "args": [
           "-y",
           "mcp-remote",
           "https://<gitlab.example.com>/api/v4/mcp",
           "--static-oauth-client-metadata",
           "{\"scope\": \"mcp\"}"
         ]
       }
     }
   }

4. Save the configuration and restart Claude Desktop.

5. On first connect, Claude Desktop opens a browser window for OAuth. Review and approve the request.

6. Go to Settings > Developer and verify the new GitLab MCP configuration.

7. Go to Settings > Connectors and inspect the connected GitLab MCP Server.

You can now start a new chat and ask a question depending on the available tools.

Available tools

The GitLab MCP server provides the following tools.

get_mcp_server_version

Returns the current version of the GitLab MCP server.

Example:

What version of the GitLab MCP server am I connected to?

create_issue

Creates a new issue in a GitLab project.

Example:

Create a new issue titled "Fix login bug" in project 123 with description
"Users cannot log in with special characters in password"

get_issue

Retrieves detailed information about a specific GitLab issue.

Example:

Get details for issue 42 in project 123

create_merge_request

Creates a merge request in a project.

Example:

Create a merge request in project gitlab-org/gitlab titled "Bug fix broken specs"
from branch "fix/specs-broken" into "master" and enable squash

get_merge_request

Retrieves detailed information about a specific GitLab merge request.

Example:

Get details for merge request 15 in project gitlab-org/gitlab

get_merge_request_commits

Retrieves the list of commits in a specific merge request.

Example:

Show me all commits in merge request 42 from project 123

get_merge_request_diffs

Retrieves the diffs for a specific merge request.

Example:

What files were changed in merge request 25 in the gitlab project?

get_merge_request_pipelines

Retrieves the pipelines for a specific merge request.

Example:

Show me all pipelines for merge request 42 in project gitlab-org/gitlab

get_pipeline_jobs

Retrieves the jobs for a specific CI/CD pipeline.

Example:

Show me all jobs in pipeline 12345 for project gitlab-org/gitlab

gitlab_search

Searches for a term across the entire GitLab instance with the search API. This tool is available for global, group, and project search. Available scopes depend on the search type.

Example:

Search issues for "flaky test" across GitLab

semantic_code_search

Searches for relevant code snippets in a project.

This tool is available only for projects with GitLab Duo turned on. Project files must be indexed into vector embeddings.

If this tool is invoked for a project without vector embeddings, indexing is triggered ad-hoc and the agent uses a different tool. This tool then becomes available after a few minutes.

Example:

How are authorizations managed in this project?