🦊 GitLab MCP Server

🚀 MCP Server for the GitLab API, enabling project management, file operations, and more.

✨ Features

• 🌿 Automatic Branch Creation: When creating/updating files or pushing changes, branches are automatically created if they don't exist
• 🛡️ Comprehensive Error Handling: Clear error messages for common issues
• 📚 Git History Preservation: Operations maintain proper Git history without force pushing
• 📦 Batch Operations: Support for both single-file and multi-file operations

🔧 Tools

1. `create_or_update_file`

2. `push_files`

3. `search_repositories`

4. `create_repository`

5. `get_file_contents`

6. `create_issue`

7. `create_merge_request`

8. `get_merge_request_raw_diff`

9. `fork_repository`

10. `create_branch`

• Create a new branch
• Inputs:
  • `project_id` (string): Project ID or URL-encoded path
  • `branch` (string): Name for new branch
  • `ref` (optional string): Source branch/commit for new branch
• Returns: Created branch reference

11. `get_job_logs`

• Retrieve the logs from a job
• Inputs:
  • `project_id` (string): Project ID or URL-encoded path
  • `job_id` (string): ID of the job
• Returns: The logs of the job

⚙️ Setup

🔑 Personal Access Token

Create a GitLab Personal Access Token with appropriate permissions:

• Go to User Settings > Access Tokens in GitLab
• Select the required scopes:
  • `api` for full API access
  • `read_api` for read-only access
  • `read_repository` and `write_repository` for repository operations
• Create the token and save it securely

💻 Usage with Claude Desktop

Add the following to your `claude_desktop_config.json`:

🐳 Docker

{
  "mcpServers": {
    "gitlab": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "GITLAB_PERSONAL_ACCESS_TOKEN",
        "-e",
        "GITLAB_API_URL",
        "mcp/gitlab"
      ],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "",
        "GITLAB_API_URL": "https://gitlab.com/api/v4" // Optional, for self-hosted instances
      }
    }
  }
}

📦 NPX

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-gitlab"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "",
        "GITLAB_API_URL": "https://gitlab.com/api/v4" // Optional, for self-hosted instances
      }
    }
  }
}

🏗️ Build

Docker build:

docker build -t vonwig/gitlab:mcp -f src/gitlab/Dockerfile .

🌍 Environment Variables

• `GITLAB_PERSONAL_ACCESS_TOKEN`: Your GitLab personal access token (required)
• `GITLAB_API_URL`: Base URL for GitLab API (optional, defaults to `https://gitlab.com/api/v4`)