mcp-gitlab

# GitLab MCP Server A Model Context Protocol (MCP) server that enables you to interact with your GitLab account. Get diffs, analyze merge requests, review code, cherry-pick changes, and more. ## Features This MCP server provides comprehensive tools for interacting with GitLab repositories, including: ### Core Repository Features - Listing projects and retrieving details - Managing branches and repositories - Working with merge requests and diffs - Adding comments and internal notes to merge requests - Updating merge request attributes - Listing and working with issues - Getting and comparing repository file contents ### Project Settings & Integrations - Managing project integrations and services - Configuring and controlling Slack integration - Setting up, updating, and testing webhooks ### CI/CD Management - Working with pipeline trigger tokens - Managing CI/CD variables - Triggering and controlling pipelines ### User & Group Administration - Listing and managing users - Working with groups and group memberships - Managing project members and access levels ## 🚀 Perfect Match: MCP-Workflow Integration **MCP-GitLab + MCP-Workflow = GitLab Development Superpowers!** This MCP server works seamlessly with [MCP-Workflow](https://github.com/atla-digital/mcp-workflow) to provide structured, workflow-driven GitLab development. Together, they deliver: ### 🔄 **Structured GitLab Operations** - **Guided Development**: Follow proven workflows for every GitLab operation - **Code Review Excellence**: Systematic merge request reviews with comprehensive feedback - **Issue Management**: Step-by-step issue analysis and resolution workflows ### 🎯 **Workflow-Driven GitLab** - **Consistent Process**: Every GitLab action follows established, repeatable workflows - **Never Get Lost**: Complex operations broken down into clear, sequential steps - **Quality Assurance**: Built-in validation and quality gates throughout ### 💡 **Real-World Example** ```bash # 1. Agent uses MCP-Workflow to start "GitLab Merge Request Review" workflow_get_step("gitlab-mr-review") # 2. Workflow guides systematic MR analysis using this MCP server gitlab_get_merge_request(project_id="web/runner", merge_request_iid=45) gitlab_get_merge_request_changes(project_id="web/runner", merge_request_iid=45) # 3. Agent follows workflow to provide line-specific code feedback gitlab_create_merge_request_discussion( project_id="web/runner", merge_request_iid=45, body="Consider using a constant for this magic number", position={ base_sha: "abc123...", head_sha: "def456...", old_path: "src/utils.js", new_path: "src/utils.js", new_line: 42 } ) # 4. Workflow ensures comprehensive review completion workflow_get_step("review-completion-checklist") ``` ### 🏆 **Why This Combination Works** - **🧭 Guided Navigation**: MCP-Workflow provides the roadmap, this server provides the GitLab tools - **🔒 Consistency**: Same high-quality process every time, regardless of project complexity - **⚡ Efficiency**: No more wondering "what's next?" - structured workflows guide every step - **🎨 Flexibility**: 29+ interconnected workflows covering every GitLab development scenario - **🔄 Context Preservation**: Workflow state maintained across long development sessions - **🎯 Precision**: Line-specific code comments with full GitLab discussion threading - **🛡️ Quality**: Built-in review gates, security analysis, and best practice enforcement **Get Started**: Install both MCP servers and experience structured GitLab development! ### 🔧 **This MCP Server Provides** - **70+ GitLab Tools**: Complete API coverage for repositories, merge requests, issues, CI/CD, webhooks - **Line-Level Code Comments**: Precise feedback with `gitlab_create_merge_request_discussion` - **Multi-Client Support**: Concurrent access for team collaboration - **Session Management**: Robust session handling with automatic recovery - **Production Ready**: Comprehensive logging, monitoring, and error handling ## Installation ### Option 1: Using Pre-built Docker Image (Recommended) The easiest way to run the GitLab MCP Server is using the pre-built Docker image: ```bash # Pull the latest image docker pull ghcr.io/atla-digital/mcp-gitlab:latest # Run the container docker run -d -p 3001:3000 --name mcp-gitlab-server ghcr.io/atla-digital/mcp-gitlab:latest ``` The server will be available at `http://localhost:3001/mcp` ### Option 2: Using Docker Compose Create a `docker-compose.yml` file: ```yaml services: mcp-gitlab: image: ghcr.io/atla-digital/mcp-gitlab:latest ports: - "3001:3000" restart: unless-stopped ``` Then run: ```bash docker compose up -d ``` ### Option 3: Building from Source If you want to build from source or contribute to the project: #### Prerequisites - Node.js (v16 or higher) - npm - A GitLab account with an API token #### Setup 1. Clone the repository: ```bash git clone https://github.com/atla-digital/mcp-gitlab.git cd mcp-gitlab ``` 2. Install dependencies: ```bash npm install ``` 3. Build the server: ```bash npm run build ``` 4. Install git hooks (optional, but recommended for contributors): ```bash npm run install-hooks ``` This installs a pre-commit hook that automatically regenerates TOOLS.md when src/utils/tools-data.ts changes. 5. Deploy the server: ```bash docker compose up --build -d ``` The server will be available at `http://localhost:3001/mcp` ### Configuration This server implements **Streamable HTTP** as the primary MCP transport, which is now natively supported by Claude Code. #### For Claude Code/Desktop (Recommended) The easiest way to add the GitLab MCP server is using the Claude CLI: ```bash # For GitLab.com claude mcp add sm-gitlab http://host.docker.internal:3001/mcp \ --transport http \ --scope user \ -H "X-GitLab-Token: YOUR_GITLAB_API_TOKEN" \ -H "X-GitLab-URL: https://gitlab.com" # For self-hosted GitLab claude mcp add sm-gitlab http://host.docker.internal:3001/mcp \ --transport http \ --scope user \ -H "X-GitLab-Token: YOUR_GITLAB_API_TOKEN" \ -H "X-GitLab-URL: https://your-gitlab-instance.com" ``` #### Manual Configuration (Alternative) Alternatively, you can manually add the following to your MCP settings file (`~/.claude.json`): ```json { "mcpServers": { "sm-gitlab": { "type": "http", "url": "http://host.docker.internal:3001/mcp", "headers": { "X-GitLab-Token": "YOUR_GITLAB_API_TOKEN", "X-GitLab-URL": "https://your-gitlab-instance.com" } } } } ``` #### Configuration Details - **`X-GitLab-Token`**: Your GitLab API token (required) - **`X-GitLab-URL`**: Your GitLab instance URL (optional, defaults to `https://gitlab.com`) **Important Notes:** - The server automatically appends `/api/v4` to the GitLab URL if not present - Only GitLab API v4 is supported - You can generate a token in your GitLab account under Settings > Access Tokens **Example GitLab URLs:** ```bash # For GitLab.com -H "X-GitLab-URL: https://gitlab.com" # For self-hosted GitLab -H "X-GitLab-URL: https://your-gitlab-instance.com" # Already includes /api/v4 (also works) -H "X-GitLab-URL: https://gitlab.com/api/v4" ``` #### Environment Configuration The server supports configuration via environment variables with validation and sensible defaults: ```bash # Copy the example configuration cp .env.example .env # Edit with your values nano .env ``` **Available Configuration Options:** | Variable | Description | Default | |----------|-------------|---------| | `PORT` | Server port | `3000` | | `NODE_ENV` | Environment (development/production/test) | `development` | | `LOG_LEVEL` | Logging level (error/warn/info/http/debug) | `info` | | `SESSION_MAX_AGE` | Session lifetime in milliseconds | `604800000` (7 days) | | `SESSION_CLEANUP_INTERVAL` | Session cleanup interval in milliseconds | `300000` (5 minutes) | | `AXIOS_TIMEOUT` | HTTP request timeout in milliseconds | `30000` (30 seconds) | | `ENABLE_REQUEST_LOGGING` | Enable detailed API request logging | `true` | | `ENABLE_DETAILED_ERRORS` | Enable detailed error messages | `false` | **Example `.env` file:** ```env PORT=3000 NODE_ENV=development LOG_LEVEL=info SESSION_MAX_AGE=604800000 SESSION_CLEANUP_INTERVAL=300000 AXIOS_TIMEOUT=30000 ENABLE_REQUEST_LOGGING=true ENABLE_DETAILED_ERRORS=false ``` #### Logging & Monitoring The server features comprehensive structured logging with Winston: **Log Components:** - **API Logger**: GitLab API requests and responses - **Session Logger**: Session creation, cleanup, and lifecycle - **Server Logger**: HTTP server events and errors - **Auth Logger**: Authentication and authorization events **Log Formats:** - **Console**: Colorized, human-readable format for development - **Files**: JSON format in production (saved to `logs/` directory) **Log Level Control:** Set the `LOG_LEVEL` environment variable to control verbosity: - `error`: Only errors - `warn`: Warnings and errors - `info`: General information, warnings, and errors (default) - `http`: HTTP requests/responses plus above - `debug`: Detailed debugging information plus above **Production Logging:** ```bash # Set log level for production LOG_LEVEL=warn NODE_ENV=production npm start # View logs in production tail -f logs/combined.log tail -f logs/error.log ``` ### Updating to Latest Version To update to the latest version when using the pre-built Docker image: ```bash # Stop the current container docker stop mcp-gitlab-server docker rm mcp-gitlab-server # Pull the latest image docker pull ghcr.io/atla-digital/mcp-gitlab:latest # Run with the new image docker run -d -p 3001:3000 --name mcp-gitlab-server ghcr.io/atla-digital/mcp-gitlab:latest ``` Or if using Docker Compose: ```bash docker compose pull docker compose up -d ``` ## Available Tools For a complete list of available tools and their parameters, see [TOOLS.md](./TOOLS.md). ## Example Usage Here are examples of how to use these tools with AI assistants that support MCP: ### List your projects ``` Could you list my GitLab projects? ``` ### Get information about a specific merge request ``` Can you show me the details of merge request with ID 123 in the project 'mygroup/myproject'? ``` ### Add a comment to a merge request ``` Please add a comment to merge request 123 in project 'mygroup/myproject' saying "This looks good, but please add more tests." ``` ### Add an internal note to a merge request ``` Add an internal note to merge request 123 in project 'mygroup/myproject' that says "Needs security review before merging." Make sure it's only visible to team members. ``` ### Update a merge request title and description ``` Update the title of merge request 123 in project 'mygroup/myproject' to "Fix login page performance issues" and update the description to include "This PR addresses the slow loading times on the login page by optimizing database queries." ``` ### Compare branches ``` Compare the 'feature-branch' with 'main' in the project 'mygroup/myproject' and show me the differences. ``` ## Practical Workflows ### Reviewing a Merge Request ``` 1. Show me merge request 123 in project 'mygroup/myproject' 2. Show me the changes for this merge request 3. Add an internal note with my review comments 4. Update the merge request title to better reflect the changes ``` ### Project Exploration ``` 1. List all my GitLab projects 2. Show me the details of project 'mygroup/myproject' 3. List all branches in this project 4. Show me the content of the README.md file in the main branch ``` ## Available Resources ### gitlab://projects List of GitLab projects accessible with your API token. ## Integration with AI Assistants The GitLab MCP Server integrates with AI assistants that support the Model Context Protocol (MCP). ### Capabilities When connected to an AI assistant, this server enables the assistant to: 1. **View and analyze code**: The assistant can fetch file contents, view branch differences, and examine merge request changes for better code understanding. 2. **Provide code reviews**: The assistant can analyze merge requests and provide feedback through comments or internal notes. 3. **Manage project workflows**: The assistant can update merge request attributes, add comments, and help with repository management tasks. 4. **Explore project structure**: The assistant can browse projects, branches, and files to understand the codebase structure. 5. **Configure CI/CD and integrations**: The assistant can help set up webhooks, manage CI/CD variables, and configure project integrations. ### Getting the Most from AI Assistant Integration - Be specific when asking about projects, merge requests, or files - Provide project IDs or paths when possible - Use the assistant for code review by asking it to analyze specific merge requests - Have the assistant help with repository configuration and management tasks - Use internal notes for team-only feedback on merge requests ## License MIT