@amgisllc/gitlab-mcp

GitLab MCP Server

MCP Server for the GitLab API, enabling comprehensive project management, file operations, CI/CD, and more.

Quick Start

• Get a GitLab Personal Access Token

  • Go to GitLab Settings > Access Tokens
  • Create token with scopes: api, read_repository, write_repository

• Install the Package

  From GitLab Package Registry (Recommended):

  # Configure npm to use GitLab registry for @amgis scope
  npm config set @amgis:registry https://gitlab.com/api/v4/packages/npm/
  
  # Install the package
  npm install -g @amgisllc/gitlab-mcp
  

  Or use directly with npx:

  npx @amgisllc/gitlab-mcp
  

• Configure in Claude Desktop Add to claude_desktop_config.json:

  {
    "mcpServers": {
      "gitlab": {
        "command": "npx",
        "args": ["-y", "@amgisllc/gitlab-mcp"],
        "env": {
          "GITLAB_PERSONAL_ACCESS_TOKEN": "your-token-here"
        }
      }
    }
  }
  

• Start Using

  • Restart Claude Desktop
  • The GitLab tools are now available!

Features

• Comprehensive GitLab API Coverage: Access to projects, issues, merge requests, pipelines, wikis, and more
• Automatic Branch Creation: When creating/updating files or pushing changes, branches are automatically created if they don't exist
• Full Project Management: Create, update, delete, and manage GitLab projects
• Issue & MR Management: Complete issue and merge request workflows including comments
• CI/CD Integration: Monitor and control pipelines and jobs
• Team Collaboration: Manage project members and permissions
• Git History Preservation: Operations maintain proper Git history without force pushing
• Batch Operations: Support for both single-file and multi-file operations

Example Usage

Once configured, you can use natural language to interact with GitLab:

• "List all open issues in project gitlab-org/gitlab"
• "Create a new branch called feature/new-feature from main"
• "Update the README.md file in my project"
• "Show me the recent commits in the repository"
• "Create a merge request from feature branch to main"
• "Check the status of the latest pipeline"
• "Add a comment to issue #123"

Tools

Repository Management

• get_project - Get detailed project information
• delete_project - Delete a GitLab project
• update_project - Update project settings (description, visibility, etc.)
• list_projects - List user's projects with filtering and pagination
• search_repositories - Search for GitLab projects
• create_repository - Create a new GitLab project
• fork_repository - Fork a project to your account or namespace

File Operations

• get_file_contents - Get contents of a file or directory
• create_or_update_file - Create or update a single file in a project
• push_files - Push multiple files in a single commit
• get_repository_archive - Download repository archive as tar.gz or zip

Branch & Tag Management

• create_branch - Create a new branch
• list_branches - List all branches in a project
• delete_branch - Delete a branch
• create_tag - Create a new tag
• list_tags - List all tags in a project
• delete_tag - Delete a tag

Issue Management

• create_issue - Create a new issue
• list_issues - List issues with filtering options
• get_issue - Get specific issue details
• update_issue - Update an existing issue
• close_issue - Close an issue
• list_issue_comments - List comments on an issue
• add_issue_comment - Add a comment to an issue

Merge Request Management

• create_merge_request - Create a new merge request
• list_merge_requests - List merge requests with filtering
• get_merge_request - Get specific merge request details
• update_merge_request - Update merge request (title, description, etc.)
• merge_merge_request - Accept/merge a merge request
• close_merge_request - Close a merge request without merging
• list_merge_request_comments - List comments on a merge request
• add_merge_request_comment - Add a comment to a merge request

Pipeline & CI/CD

• list_pipelines - List project pipelines with filtering
• get_pipeline - Get pipeline details
• trigger_pipeline - Trigger a new pipeline
• cancel_pipeline - Cancel a running pipeline
• list_jobs - List pipeline jobs
• get_job_log - Get job log output

Wiki & Documentation

• list_wiki_pages - List wiki pages in a project
• get_wiki_page - Get wiki page content
• create_wiki_page - Create a new wiki page
• update_wiki_page - Update wiki page content

Team & Permissions

• list_project_members - List project members
• add_project_member - Add a member to the project
• remove_project_member - Remove a member from the project
• update_member_access - Update member's access level

Releases

• list_releases - List project releases
• create_release - Create a new release
• update_release - Update release information
• delete_release - Delete a release

Snippets

• list_snippets - List project snippets
• create_snippet - Create a new snippet
• get_snippet - Get snippet content
• update_snippet - Update snippet content

Repository Operations

• list_commits - List commits with filtering options
• get_commit - Get specific commit details
• compare_branches - Compare two branches or commits

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",
        "@amgisllc/gitlab-mcp"
      ],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>",
        "GITLAB_API_URL": "https://gitlab.com/api/v4" // Optional, for self-hosted instances
      }
    }
  }
}

Usage with Claude CLI

For system-wide configuration with Claude CLI, add to ~/.claude/settings.json:

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-gitlab"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "your-token-here",
        "GITLAB_API_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}

Or use Docker:

{
  "mcpServers": {
    "gitlab": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "GITLAB_PERSONAL_ACCESS_TOKEN", "mcp/gitlab"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}

Then simply run:

claude

Usage with VS Code

For quick installation, use one of the one-click installation buttons below...

For manual installation, add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing Ctrl + Shift + P and typing Preferences: Open User Settings (JSON).

Optionally, you can add it to a file called .vscode/mcp.json in your workspace. This will allow you to share the configuration with others.

Note that the mcp key is not needed in the .vscode/mcp.json file.

Docker

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "gitlab_token",
        "description": "GitLab Personal Access Token",
        "password": true
      },
      {
        "type": "promptString",
        "id": "gitlab_url",
        "description": "GitLab API URL (optional)",
        "default": "https://gitlab.com/api/v4"
      }
    ],
    "servers": {
      "gitlab": {
        "command": "docker",
        "args": [
          "run",
          "--rm",
          "-i",
          "mcp/gitlab"
        ],
        "env": {
          "GITLAB_PERSONAL_ACCESS_TOKEN": "${input:gitlab_token}",
          "GITLAB_API_URL": "${input:gitlab_url}"
        }
      }
    }
  }
}

NPX

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "gitlab_token",
        "description": "GitLab Personal Access Token",
        "password": true
      },
      {
        "type": "promptString",
        "id": "gitlab_url",
        "description": "GitLab API URL (optional)",
        "default": "https://gitlab.com/api/v4"
      }
    ],
    "servers": {
      "gitlab": {
        "command": "npx",
        "args": [
          "-y",
          "@amgisllc/gitlab-mcp"
        ],
        "env": {
          "GITLAB_PERSONAL_ACCESS_TOKEN": "${input:gitlab_token}",
          "GITLAB_API_URL": "${input:gitlab_url}"
        }
      }
    }
  }
}

Installation

GitLab Package Registry Authentication

To install packages from GitLab Package Registry, you need to authenticate. You have several options:

• Personal Access Token (Recommended for development)

  • Go to GitLab > User Settings > Access Tokens
  • Create a token with read_api scope (or api for full access)
  • Use this token in your .npmrc configuration

• Deploy Token (Recommended for CI/CD)

  • Go to Project > Settings > Repository > Deploy Tokens
  • Create a token with read_package_registry scope
  • Use username and token for authentication

• CI Job Token (For GitLab CI/CD)

  • Automatically available in CI/CD pipelines as $CI_JOB_TOKEN
  • No configuration needed when running in GitLab CI

From GitLab Package Registry

First, configure npm to use the GitLab Package Registry for the @amgis scope:

npm install -g @amgisllc/gitlab-mcp

From Source

git clone https://github.com/modelcontextprotocol/servers.git
cd servers/src/gitlab
npm install
npm run build

Development

Building

npm install
npm run build

Testing

The project includes a comprehensive test suite covering all GitLab operations.

# Setup test environment
cp .env.example .env
# Edit .env with your GitLab token and test project

# Run all tests
npm test

# Run specific test suites
npm run test:issues      # Issue operations
npm run test:files       # File operations
npm run test:mr          # Merge requests
npm run test:ci          # CI/CD pipelines

See tests/README.md for detailed testing documentation.

Docker Build

docker build -t mcp/gitlab .

Project ID Format

All tools accept project_id parameter in two formats:

• Numeric ID: "12345" (as a string)
• URL-encoded path: "namespace/project" or "group/subgroup/project"

Example:

// Both are valid:
{ "project_id": "12345678" }
{ "project_id": "gitlab-org/gitlab" }

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)

Troubleshooting

Common Issues

• Authentication Failed

  • Ensure your personal access token has the required scopes: api, read_repository, write_repository
  • Check token expiration date
  • For self-hosted GitLab, verify the GITLAB_API_URL is correct

• Project Not Found

  • Verify you have access to the project
  • Use the correct project ID format (string, not number)
  • For private projects, ensure your token has appropriate permissions

• Rate Limiting

  • GitLab has API rate limits (2000 requests/min for authenticated users)
  • Consider implementing request batching for bulk operations

• Self-Hosted GitLab

  • Set GITLAB_API_URL to your instance: https://gitlab.example.com/api/v4
  • Ensure your instance version supports the API endpoints (GitLab 14.0+)

Claude Desktop Issues

• MCP not available: Restart Claude Desktop after configuration changes
• Token not working: Check that the token is properly quoted in the JSON config
• Server not starting: Check logs in Claude Desktop developer console

Claude CLI Issues

• MCP server not loading: Check ~/.claude/settings.json syntax
• Debug MCP connections: Run claude --debug to see detailed logs
• Verify configuration: Run claude config get mcpServers
• Docker issues: Ensure Docker is running and the image is built

Requirements

• Node.js 18+
• GitLab account with personal access token
• GitLab 14.0+ (for self-hosted instances)

Publishing & CI/CD

This project uses GitLab CI/CD to automatically build, test, and publish the package.

Automatic Publishing

The package is automatically published to GitLab Package Registry when:

• A new git tag is created (e.g., v1.0.1)
• The CI/CD pipeline passes all tests

To create a new release:

git tag v1.0.1
git push origin v1.0.1

Manual Publishing

To manually publish to npm:

npm login
npm publish --access public

CI/CD Pipeline

The .gitlab-ci.yml file defines three stages:

• Build - Compiles TypeScript to JavaScript
• Test - Runs the full test suite
• Publish - Publishes to GitLab Package Registry (on tags only)

Contributing

Contributions are welcome! Please see the tests documentation for information on running the test suite.

Adding New Tools

• Implement the tool in index.ts and/or api-functions.ts
• Add schema definitions in schemas.ts
• Add comprehensive tests in tests/features/
• Update this README with the new tool documentation

Security

• Never commit tokens: Use environment variables for all sensitive data
• Token scopes: Use minimum required scopes for your use case
• Audit logs: GitLab tracks API usage - review your audit logs regularly

License

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