GitLab MCP Server: Streamlining Project Management and File Operations

The GitLab MCP Server is a powerful integration with the GitLab API, designed to simplify project management, file operations, and repository workflows. This server enables seamless interaction with GitLab projects, offering features like automatic branch creation, batch operations, and comprehensive error handling.

Key Features

• Automatic Branch Creation: Automatically creates branches when files are created or updated.
• Comprehensive Error Handling: Provides clear error messages for common issues.
• Git History Preservation: Ensures operations maintain proper Git history without force pushing.
• Batch Operations: Supports both single-file and multi-file operations.

Tools and Functionality

1. create_or_update_file

• Purpose: Create or update a single file in a project.
• Inputs: project_id, file_path, content, commit_message, branch, previous_path (optional).
• Returns: File content and commit details.

2. push_files

• Purpose: Push multiple files in a single commit.
• Inputs: project_id, branch, files, commit_message.
• Returns: Updated branch reference.

3. search_repositories

• Purpose: Search for GitLab projects.
• Inputs: search, page (optional), per_page (optional).
• Returns: Project search results.

4. create_repository

• Purpose: Create a new GitLab project.
• Inputs: name, description (optional), visibility (optional), initialize_with_readme (optional).
• Returns: Created project details.

5. get_file_contents

• Purpose: Get contents of a file or directory.
• Inputs: project_id, file_path, ref (optional).
• Returns: File/directory contents.

6. create_issue

• Purpose: Create a new issue.
• Inputs: project_id, title, description (optional), assignee_ids (optional), labels (optional), milestone_id (optional).
• Returns: Created issue details.

7. create_merge_request

• Purpose: Create a new merge request.
• Inputs: project_id, title, description (optional), source_branch, target_branch, draft (optional), allow_collaboration (optional).
• Returns: Created merge request details.

8. fork_repository

• Purpose: Fork a project.
• Inputs: project_id, namespace (optional).
• Returns: Forked project details.

9. create_branch

• Purpose: Create a new branch.
• Inputs: project_id, branch, ref (optional).
• Returns: Created branch reference.

Setup and Configuration

Personal Access Token

To use the GitLab MCP Server, you need a GitLab Personal Access Token with the appropriate permissions:
- Scopes: api, read_api, read_repository, write_repository.
- Steps: Go to User Settings > Access Tokens in GitLab, select the required scopes, and create the token.

Usage with Claude Desktop

Add the following configuration 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"
      }
    }
  }
}

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"
      }
    }
  }
}

Build Instructions

To build the Docker image:

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

License

This MCP server is licensed under the MIT License. You are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, see the LICENSE file in the project repository.