GitLab MCP Server

A comprehensive Model Context Protocol (MCP) server that provides seamless GitLab API integration for Claude Desktop and other MCP clients. Manage your entire GitLab workflow through natural language commands - from project creation to repository operations, CI/CD management, and team collaboration.

🚀 Quick Start

# Install with uvx (recommended)
uvx --from gitlab-clone-mcp-server gitlab-mcp

# Or install as a tool
uv tool install gitlab-clone-mcp-server

🔌 Transport Options

GitLab MCP Server supports three transport types:

# Run with stdio transport (default)
gitlab-mcp stdio

# Run with SSE transport
gitlab-mcp sse --host localhost --port 8000

# Run with Streamable HTTP transport (recommended for production)
gitlab-mcp streamable-http --host localhost --port 8000

See TRANSPORT_OPTIONS.md for detailed configuration.

✨ Key Features

• Complete GitLab Integration: 46+ tools covering all major GitLab operations
• Natural Language Interface: Control GitLab through conversational commands
• Zero Configuration: Works out-of-the-box with your GitLab Personal Access Token
• Comprehensive Coverage: Projects, repositories, issues, merge requests, CI/CD, and more
• Local Repository Cloning: Clone repositories directly to your local machine
• Batch Operations: Perform bulk operations across multiple projects

🛠️ Available Tools (46 Total)

📁 Project Management (12 tools)

📝 Issue Management (4 tools)

🔀 Merge Request Management (2 tools)

📄 File Operations (5 tools)

🌿 Repository & Git Operations (15 tools)

🚀 CI/CD Operations (3 tools)

👥 Groups & Collaboration (3 tools)

Installation

Using uvx (Recommended)

uvx --from gitlab-clone-mcp-server gitlab-mcp

Using uv

uv tool install gitlab-mcp-server

From source

git clone <repository-url>
cd gitlab-mcp
uv sync

Setup

1. Get GitLab Personal Access Token:

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

2. Set environment variables:

   export GITLAB_TOKEN="your_token_here"
   export GITLAB_URL="https://gitlab.com"  # optional
   

3. Test the server:

   gitlab-mcp
   

Configuration

Claude Desktop Configuration

Add to your Claude Desktop config (%APPDATA%\Claude\claude_desktop_config.json):

Using stdio transport (recommended)

{
  "mcpServers": {
    "gitlab": {
      "command": "uvx",
      "args": [
        "--from", "gitlab-clone-mcp-server",
        "gitlab-mcp", "stdio"
      ],
      "env": {
        "GITLAB_URL": "https://gitlab.com",
        "GITLAB_TOKEN": "your_gitlab_token_here"
      }
    }
  }
}

Using HTTP transport

If you're running the server with Streamable HTTP transport:

{
  "mcpServers": {
    "gitlab": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "GITLAB_TOKEN": "your_gitlab_token_here"
      }
    }
  }
}

Headers Integration

For applications using MCPToolset, connect with headers:

import os
from mcp_toolset import MCPToolset, SseServerParams

gitlab_tools = MCPToolset(
    connection_params=SseServerParams(
        url="http://localhost:8000/sse",
        headers={"GITLAB_TOKEN": os.getenv("GITLAB_TOKEN")},
    )
)

💬 Usage Examples

Control GitLab through natural language commands:

Project Management:

• "Create a new private project called 'microservice-api'"
• "Fork the kubernetes/dashboard project to my namespace"
• "Archive the old legacy-system project"

Issue & Code Review:

• "Show all open issues in the backend-service project"
• "Create merge request from feature/auth-system to main branch"
• "Merge the approved MR #23 in mobile-app project"

Repository Operations:

• "Create a new config.yaml file with database configuration"
• "Show all branches in the web-application project"
• "Clone the microservices-platform project to ./local-dev"

CI/CD & Teams:

• "Show running pipelines for the deployment project"
• "List all my GitLab groups and their members"

🔧 Authentication Setup

GitLab Personal Access Token

1. Go to GitLab → Settings → Access Tokens
2. Create token with these scopes:
   • ✅ api - Full API access
   • ✅ read_repository - Read repository data
   • ✅ write_repository - Write repository data
   • ✅ read_user - Read user information
3. Copy the generated token

Environment Variables

🔒 Security Best Practices

• Never commit tokens to version control
• Use environment variables for token storage
• Set token expiration dates when possible
• Rotate tokens regularly for enhanced security
• Use minimal required scopes for your use case

🐛 Troubleshooting

Token Issues:

• ❌ GITLAB_TOKEN not set → Set environment variable or provide in headers
• ❌ 401 Unauthorized → Check token permissions and validity
• ❌ 403 Forbidden → Verify project access permissions

Git Operations:

• ❌ Git command not found → Install Git and add to PATH

Test Connection:

curl -H "PRIVATE-TOKEN: your_token" "https://gitlab.com/api/v4/user"

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Related Projects

• Model Context Protocol
• Claude Desktop
• GitLab API Documentation

Made with ❤️ for the GitLab and MCP community