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 as MCP client
• Podman(If running as containers)

Quick Start

1. Get the code

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

2. Build the image & configure Cursor
   This also creates a ~/.rh-gitlab-mcp.env file like this.

make setup

3. Prepare a GitLab token
   • Go to ${GITLAB_URL} if no custom gitlab defaults to public gitlab.com and create a token
   • Edit the .rh-gitlab-mcp.env file in your home directory and paste in the token.

To confirm it's working, run Cursor, go to Settings and click on "Tools & Integrations". Under MCP Tools you should see "gitlabMcp" with 8 tools enabled.

Available Functions

🔍 Search & Discovery

• search_repositories - Find projects by name, description, or path
• list_issues - List issues in a project
• list_merge_requests - List merge requests in a project
• list_pipelines - List pipelines in a project
• list_jobs - List jobs in a specific pipeline

📊 Monitoring & Analysis

• check_latest_failed_jobs - Find recent failed jobs across pipelines
• list_latest_commits - View recent commits in projects

Correct Query Patterns

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"

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

Function Details

search_repositories

{
  "search_term": "mcp-servers",  // Optional: project name/description
  "visibility": "all",             // public, private, internal, all
  "owned": false,                  // true for only owned repos
  "limit": 10                      // max results
}

check_latest_failed_jobs

{
  "project_id": "123",            // Required: GitLab project ID
  "limit": 5                      // Optional: max failed jobs to return
}

list_issues

{
  "project_id": "123",            // Required: GitLab project ID
  "state": "opened",              // opened, closed, all
  "limit": 20                     // max results
}

list_pipelines

{
"project_id": "123",            // Required: GitLab project ID
"status": "all",                // running, pending, success, failed, all
"limit": 20                     // max results
}

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

Environment Configuration

# Required
export MCP_GITLAB_TOKEN="your-gitlab-token"

# Optional
export GITLAB_URL="https://gitlab.example.com"
export MCP_MAX_API_CALLS="100"
export MCP_ALLOWED_ACTIONS="read"
export MCP_ALLOWED_REPOS="project1,project2"  # Empty = all allowed

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

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

Best Practices

🎯 Be Specific

• Include project names in queries
• Specify what information you want (issues, MRs, pipelines, etc.)
• Use descriptive terms rather than abbreviations

🔄 Multi-Step Queries

The MCP can now handle complex queries that require multiple steps:

1. Search for project by name
2. Get specific information about that project
3. Drill down into details as needed

📊 Use Filters

Most functions support filtering:

• States: opened, closed, merged, failed, success
• Limits: Control result size for performance
• Visibility: Focus on relevant repositories

Troubleshooting

Common 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 if needed

🚫 "Access denied"

• Check MCP_ALLOWED_REPOS configuration
• Verify your GitLab token has proper permissions
• Ensure you're a project member

This read-only approach provides safer, more focused GitLab integration for monitoring and analysis workflows.