🦊 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)