GitLab MCP Server

How to use

You interact with the GitLab MCP Server through your MCP client by asking natural language questions. You can request lists of merge requests, view details for a specific MR, inspect reviews and discussions, see test summaries, and examine pipelines and job logs. For example, you can ask for the open MRs, view the full details for MR #456, or pull the test summary for MR #456. The server translates your questions into GitLab API calls and returns structured results that you can discuss or act on in your chat.

How to install

Prerequisites: you need Python tooling managed by uv and a working shell. Install uv first if it is not already present.

# macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or install via pip
pip install uv

1. Install the MCP server locally.

git clone https://github.com/FitoDomik/gitlab-mcp-server.git
cd gitlab-mcp-server
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .
chmod +x run-mcp.sh

2. Obtain a GitLab access token with read_api scope.

# In GitLab, go to Settings → Access Tokens
# Create a token with read_api permission and copy the token

3. Create project-specific configuration file for GitLab access.

# Create a file named gitlab-mcp.env in your project directory
GITLAB_PROJECT_ID=12345
GITLAB_ACCESS_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
GITLAB_URL=https://gitlab.com

4. Connect the MCP server to your Cursor by creating a local MCP config.

# Create a file at .cursor/mcp.json in your project
{
  "mcpServers": {
    "gitlab-mcp": {
      "command": "/path/to/gitlab-mcp-server/run-mcp.sh",
      "cwd": "/path/to/your/project"
    }
  }
}

5. Restart Cursor and start asking questions about GitLab.

Configuration

Project-wide and local configurations are used to connect to GitLab securely. Do not commit tokens to version control.

Global environment variables (optional) can be set in your shell to reuse the settings across sessions.

Troubleshooting

Authentication error: Ensure the token has read_api scope and has not expired.

Project not found: Confirm the numeric Project ID is correct.

Connection issues: Verify that the GitLab URL is reachable and correctly specified.

Script not found: Make sure the path in the MCP configuration points to the correct server script and that it is executable.

Notes on usage patterns

Use the MCP to fetch: a) lists of merge requests with filters, b) detailed MR information, c) reviews and discussions, d) test summaries and detailed test reports, e) pipeline statuses, and f) logs for specific jobs. You can also search for MRs by a branch name and respond to discussion threads directly from the chat.

Security considerations

Keep the GitLab access token secure. Do not share the token or commit it in public repositories. Use project-scoped tokens and rotate them as needed.

list_merge_requests

Fetch a list of merge requests with optional filters like state and target branch.

get_merge_request_details

Retrieve detailed information for a specific merge request by IID.

get_pipeline_test_summary

Get a quick summary of tests for a given merge request.

get_merge_request_test_report

Obtain a detailed test report for a merge request.

get_merge_request_pipeline

View the pipeline and all jobs for a merge request.

get_job_log

Fetch logs for a specific pipeline job.

get_merge_request_reviews

Retrieve all reviews and discussions for a merge request.

get_commit_discussions

View discussions on commits within a merge request.

get_branch_merge_requests

Find merge requests associated with a specific branch name.

reply_to_review_comment

Post a reply to an existing review comment on a merge request.