martijndormans/mcp-gitlab

🦊 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

   • Create or update a single file in a project
   • Inputs:
     • project_id (string): Project ID or URL-encoded path
     • file_path (string): Path where to create/update the file
     • content (string): Content of the file
     • commit_message (string): Commit message
     • branch (string): Branch to create/update the file in
     • previous_path (optional string): Path of the file to move/rename
   • Returns: File content and commit details

2. push_files

   • Push multiple files in a single commit
   • Inputs:
     • project_id (string): Project ID or URL-encoded path
     • branch (string): Branch to push to
     • files (array): Files to push, each with file_path and content
     • commit_message (string): Commit message
   • Returns: Updated branch reference

3. search_repositories

   • Search for GitLab projects
   • Inputs:
     • search (string): Search query
     • page (optional number): Page number for pagination
     • per_page (optional number): Results per page (default 20)
   • Returns: Project search results

4. create_repository

   • Create a new GitLab project
   • Inputs:
     • name (string): Project name
     • description (optional string): Project description
     • visibility (optional string): 'private', 'internal', or 'public'
     • initialize_with_readme (optional boolean): Initialize with README
   • Returns: Created project details

5. get_file_contents

   • Get contents of a file or directory
   • Inputs:
     • project_id (string): Project ID or URL-encoded path
     • file_path (string): Path to file/directory
     • ref (optional string): Branch/tag/commit to get contents from
   • Returns: File/directory contents

6. create_issue

   • Create a new issue
   • Inputs:
     • project_id (string): Project ID or URL-encoded path
     • title (string): Issue title
     • description (optional string): Issue description
     • assignee_ids (optional number[]): User IDs to assign
     • labels (optional string[]): Labels to add
     • milestone_id (optional number): Milestone ID
   • Returns: Created issue details

7. create_merge_request

   • Create a new merge request
   • Inputs:
     • project_id (string): Project ID or URL-encoded path
     • title (string): MR title
     • description (optional string): MR description
     • source_branch (string): Branch containing changes
     • target_branch (string): Branch to merge into
     • draft (optional boolean): Create as draft MR
     • allow_collaboration (optional boolean): Allow commits from upstream members
   • Returns: Created merge request details

8. get_merge_request_raw_diff

   • Get a merge request information of the difference in a raw format
   • Inputs:
     • project_id (string): Project ID or URL-encoded path
     • merge_request_id (string): ID of the merge request
   • Returns: The difference of the merge request in a raw format

9. fork_repository

   • Fork a project
   • Inputs:
     • project_id (string): Project ID or URL-encoded path
     • namespace (optional string): Namespace to fork to
   • Returns: Forked project details

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": "<YOUR_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": "<YOUR_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)