GitLab MCP Server

GitLab MCP Server

Connect your AI assistant to GitLab. Ask questions like "List open merge requests", "Show me reviews for MR #123", or "Find merge requests for the feature branch" directly in your chat.

Table of Contents

• Quick Setup
• What You Can Do
• Configuration Options
• Troubleshooting
• Tool Reference
• Development
• Security Notes
• Support

Quick Setup

1. Install the server:

   git clone https://github.com/amirsina-mandegari/gitlab-mcp-server.git
   cd gitlab-mcp-server
   python -m venv .venv && source .venv/bin/activate
   pip install -r requirements.txt
   chmod +x run-mcp.sh
   

2. Get your GitLab token:

   • Go to GitLab → Settings → Access Tokens
   • Create token with read_api scope
   • Copy the token

3. Configure your project:In your project directory, create gitlab-mcp.env:

   GITLAB_PROJECT_ID=12345
   GITLAB_ACCESS_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
   GITLAB_URL=https://gitlab.com
   

4. Connect to Cursor:Create .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 GitLab questions!

What You Can Do

Once connected, try these commands in your chat:

• "List open merge requests"
• "Show me details for merge request 456"
• "Get reviews and discussions for MR #123"
• "Find merge requests for the feature/auth-improvements branch"
• "Show me closed merge requests targeting main"
• "Reply to discussion abc123 in MR #456 with 'Thanks for the feedback!'"
• "Create a new review comment in MR #789 asking about the error handling"
• "Resolve discussion def456 in MR #123"

Working with Review Comments

The enhanced review tools allow you to interact with merge request discussions:

1. First, get the reviews to see discussion IDs:

   "Show me reviews for MR #123"
   

2. Reply to specific discussions using the discussion ID:

   "Reply to discussion abc123 in MR #456 with 'I'll fix this in the next commit'"
   

3. Create new discussion threads to start conversations:

   "Create a review comment in MR #789 asking 'Could you add error handling here?'"
   

4. Resolve discussions when issues are addressed:

   "Resolve discussion def456 in MR #123"
   

Note: The get_merge_request_reviews tool now displays discussion IDs and note IDs in the output, making it easy to reference specific discussions when replying or resolving.

Configuration Options

Project-Level (Recommended)

Each project gets its own gitlab-mcp.env file with its own GitLab configuration. Keep tokens out of version control.

Global Configuration

Set environment variables system-wide instead of per-project:

export GITLAB_PROJECT_ID=12345
export GITLAB_ACCESS_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
export GITLAB_URL=https://gitlab.com

Find Your Project ID

• Go to your GitLab project → Settings → General → Project ID
• Or check the URL: https://gitlab.com/username/project (use the numeric ID)

Troubleshooting

Authentication Error: Verify your token has read_api permissions and is not expired.

Project Not Found: Double-check your project ID is correct (it's a number, not the project name).

Connection Issues: Make sure your GitLab URL is accessible and correct.

Script Not Found: Ensure the path in your MCP config points to the actual server location and the script is executable.

Tool Reference

Development

Project Structure

gitlab-mcp-server/
├── main.py              # MCP server entry point
├── config.py            # Configuration management
├── gitlab_api.py        # GitLab API client
├── run-mcp.sh          # Launch script
└── tools/              # Tool implementations

Adding Tools

1. Create new file in tools/
2. Add to list_tools() in main.py
3. Add handler to call_tool() in main.py

Testing

python test_tools.py

Security Notes

• Add gitlab-mcp.env to your .gitignore
• Never commit access tokens
• Use project-specific tokens with minimal permissions
• Rotate tokens regularly

Support

• Check GitLab API documentation
• Open issues at github.com/amirsina-mandegari/gitlab-mcp-server

License

MIT License - see LICENSE file for details.