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)
• REQUESTS_CA_BUNDLE="/path/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.

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 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

🚫 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

🚫 "Project not found"

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

🚫 "Rate limit exceeded"

• 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
• ✅ 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"