gitlab-mcp-server

Gitlab MCP (ModelContextProvider) server is a containerized Python MCP server for Cursor to provide access to GitLab API(read-only as of now).

---

📦 Installation

Prerequisites

• Cursor IDE with MCP support
• Podman for container management

Quick Start

1. Get the code

git clone [email protected]:redhat-ai-tools/gitlab-mcp.git
cd gitlab-mcp

2. Customize your environment

make customize

This creates ~/.rh-gitlab-mcp.env and opens it for editing. Configure:

• MCP_GITLAB_TOKEN="your-token-here" (get token here)
• MCP_ALLOWED_REPOS="your-repo-patterns" (see examples below)

Optional

• GITLAB_URL="https://self-hosted-gitlab.example.com" (If not set defaults to https://gitlab.com)
• SSL_CERT_PATH="/path/on/host/to/ca-bundle.crt" # if you need SSL for access

Note: Actions are hardcoded to read-only for security - write operations are never permitted.

MCP_ALLOWED_REPOS is required and specifies which repositories can be accessed using numeric group and project IDs.

⚠️ Important: Use numeric IDs only (not names or paths) for reliable access.

ID Examples:

# Specific project IDs only
export MCP_ALLOWED_REPOS="12345,67890"

# Specific group IDs (includes all projects in those groups)
export MCP_ALLOWED_REPOS="52843642,53727688"

# Mixed project and group IDs (recommended approach)
export MCP_ALLOWED_REPOS="12345,52843642,67890,53727688"

How to find IDs:

• Project ID: Visit your project in GitLab web UI → Project ID is shown below the project name
• Group ID: Visit your group in GitLab web UI → Group ID is shown in the group settings or URL
• Via API: Use GitLab API /groups or /projects endpoints to find numeric IDs

3. Build and configure

make setup

• Validates environment file exists and has required settings
• Builds the container image
• Configures Cursor MCP settings
• Provides verification instructions

Verification: Open Cursor → Settings → "Tools & Integrations" → MCP Tools. You should see "RH-GITLAB-MCP" with 8 tools enabled.

SSL Certificate Configuration

For accessing Red Hat internal GitLab (gitlab.example.com) or other corporate GitLab instances with custom CA certificates:

When SSL Certificates Are Needed:

• ✅ Accessing internal GitLab (gitlab.cee.example.com)
• ✅ Corporate GitLab instances with self-signed or custom CA certificates
• ❌ Not needed for public gitlab.com

How to Configure:

1. Edit your env file (~/.rh-gitlab-mcp.env):

   # Uncomment and set the path to your CA bundle on the HOST machine
   SSL_CERT_PATH=/etc/pki/ca-trust/some/path/pem/tls-ca-bundle.pem
   REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
   SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt

2. Re-run cursor-config:

   make cursor-config

   This will automatically detect SSL_CERT_PATH and configure the volume mount.

How It Works:

• The SSL_CERT_PATH points to the CA bundle file on your host machine
• make cursor-config mounts it into the container at /etc/ssl/certs/ca-certificates.crt
• Python libraries use REQUESTS_CA_BUNDLE and SSL_CERT_FILE to find the certs inside the container
• No container rebuild needed - it's all configuration!

Make Targets

make help          # Show all available targets and usage instructions
make build         # Build the container image only
make run           # Run the MCP server in STDIO mode
make cursor-config # Configure Cursor MCP settings only
make clean         # Remove the container image
make setup-force   # Skip environment validation (for automation/CI)

Project Structure

gitlab-mcp/
├── Makefile              # Build and deployment automation
├── gitlab_mcp_server.py  # Main MCP server implementation
├── Containerfile         # Container build configuration
├── requirements.txt      # Python dependencies
├── example.env           # Environment template
├── example.mcp.json      # Cursor MCP configuration template
└── README.md            # This documentation

Key Files:

• ~/.rh-gitlab-mcp.env - Your personal environment configuration (created by customize)
• ~/.cursor/mcp.json - Cursor MCP server configuration (updated by setup)

Step by step example:

When you ask: "List the failed jobs in mcp-servers project"

The MCP follows:

1. 🔍 Search for project: Use search_repositories with search_term="mcp-servers"
2. 📋 Get project ID: Extract the project ID from search results
3. ❌ List failed jobs: Use check_latest_failed_jobs with that project ID
4. 📊 Display results: Show the recent failed jobs with details

Security Features

• Rate limiting: Max 100 API calls per hour (configurable)
• Action restrictions: Only "read" actions allowed by default
• Repository access control: Configurable repo allowlist
• Error handling: Graceful failures with helpful messages

Available Tools:

🔍 search_repositories Purpose: Search and filter repositories across allowed scope

📋 list_issues Purpose: List issues in a specific project

🔀 list_merge_requests Purpose: List merge requests in a specific project

🏗️ list_pipelines Purpose: List CI/CD pipelines in a specific project

🔍 scan_group_failed_pipelines Purpose: Scan ALL projects in allowed groups for failed pipelines

⚙️ list_jobs Purpose: List jobs within a specific pipeline

❌ check_latest_failed_jobs Purpose: Find recent failed jobs in a project

📝 list_latest_commits Purpose: List recent commits from projects

✅ debug_config - This is a bonus command but not count as a tool, only for dev/debug purposes Purpose: For dev related questions like: Which GitLab groups and projects can I access?

Example Workflows

1. Investigate Failed Jobs

Human: "List failed jobs in mcp-tests project"
→ MCP searches for "mcp-tests" project
→ MCP gets project ID from search results  
→ MCP lists recent failed jobs with details

Note: Limitations & Behavior ⚙️

Default limit: 5 failed jobs (configurable) Pipeline scope: Searches last 20 pipelines only Chronological: Results are from most recent pipelines first Error handling: Continues if individual pipeline/job access fails Access control: Only works with projects in MCP_ALLOWED_REPOS

2. Project Health Check

Human: "Show pipeline status for my-app project"
→ MCP searches for "my-app" project
→ MCP lists recent pipelines with status
→ Human can drill down into specific pipelines

3. Issue Tracking

Human: "What open issues are there in frontend-app?"
→ MCP searches for "frontend-app" project
→ MCP lists open issues with assignees and dates

Troubleshooting

Setup Issues

** "Environment file not found" or "GitLab token not configured"**

• Run make customize first to create and configure the environment file
• Make sure to set MCP_GITLAB_TOKEN with your actual token (not the placeholder)
• Set MCP_ALLOWED_REPOS with your repository patterns
• Provide the absolute path of env files, volumes, cert paths

** Editor doesn't open during make customize**

• Set your preferred editor: export EDITOR=vim (or code, nano, etc.)
• Or manually edit ~/.rh-gitlab-mcp.env after running make customize

** Cursor not showing MCP tools**

• Verify setup completed successfully: make setup should show "Setup completed successfully!"
• Check that ~/.cursor/mcp.json contains the RH-GITLAB-MCP entry
• Restart Cursor after configuration changes

Runtime Issues

** TLS or SSL errors, while accessing internal repositories(This is not required for gitlab.com repos):

• make sure you have SSL_CERT_PATH set to absolute path to your certs file in the env file
• If you are on MAC OS it podman may not recognize some locations so better to copy the certs.pem file to your home directory & set that path in SSL_CERT_PATH
• Make sure you have provided the exact file and not a symlink in SSL_CERT_PATH
• Make sure you have uncommented both REQUESTS_CA_BUNDLE & SSL_CERT_FILE in .rh-gitlab-mcp.env file

** "Project not found"**

• Try broader search terms
• Check if you have access to the project
• Verify project name spelling

** "Rate limit exceeded"**(Only if you have set this option)

• Wait an hour for limit reset
• Increase MCP_MAX_API_CALLS in your env file

** "Access denied" or "No repositories found"**

• Use numeric IDs only in MCP_ALLOWED_REPOS (not project/group names or paths)
• Check MCP_ALLOWED_REPOS configuration in your env file
• Verify your GitLab token has proper permissions
• Verify you have not changed the key from MCP_GITLAB_TOKEN to GITLAB_TOKEN
• Ensure you're a project member
• Don't use: MCP_ALLOWED_REPOS="my-group/*,project-name"
• Use instead: MCP_ALLOWED_REPOS="52843642,53727688"

For Project Discovery

✅ Correct Prompts:

• "Search for projects containing 'systemd'"
• "Find repositories with 'kernel' in the name"
• "List my owned projects"
• "Show all public repositories"

❌ Avoid:

• Single word searches without context
• Vague terms like "find stuff"

For Failed Jobs Analysis

✅ Correct Prompts:

• "List the failed jobs in mcp-servers project"
• "Show recent failed jobs for project ID 123"
• "Find failed pipeline jobs in the last few runs"

❌ Avoid:

• Just saying "failed jobs" without specifying project

For Project Monitoring

✅ Correct Prompts:

• "Show recent pipelines for project 456"
• "List open issues in my-project"
• "Show merge requests waiting for review in project XYZ"
• "Get latest commits from all my projects"