Custom GitLab

You can connect your AI assistant to a GitLab instance through an MCP server that exposes a set of repository operations. This server enables searching projects, reading and writing files, and common actions like creating issues, merge requests, forks, and branches, all via standardized MCP endpoints.

How to use

You interact with the GitLab MCP Server through an MCP client. Use the available tools to search for GitLab projects, retrieve file contents, create or update a file, push multiple files in one commit, and perform common repository actions such as creating issues, merge requests, forking, or creating branches. Your AI assistant can orchestrate these actions across your GitLab projects, enabling automation and context-driven workflows without manual UI navigation.

How to install

Prerequisites you need before installing this MCP server:

1. Install Node.js (version 14 or higher) on the machine that will run the MCP server.

2. Ensure you have a GitLab Personal Access Token with appropriate scopes (api, read_api, read_repository, write_repository) to allow the MCP server to perform repository operations.

3. Clone the MCP server repository and install dependencies.

Configuration and runtime

Below is the MCP configuration snippet you need to run the local GitLab MCP server. Save this in your environment or a Claude/Claude Desktop config file where your MCP servers are defined.

{
  "mcpServers": {
    "github.com/modelcontextprotocol/servers/tree/main/src/gitlab": {
      "command": "node",
      "args": [
        "/path/to/custom-gitlab-server/index.js"
      ],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "your-gitlab-token",
        "GITLAB_API_URL": "https://your-gitlab-instance/api/v4"
      }
    }
  }
}

Notes on usage and security

Keep your GitLab access token secure and rotate it periodically. The server uses the token to access your repositories and perform write operations. If you are running the server behind a proxy or in a restricted network, ensure that outbound access to your GitLab instance is allowed on the API URL you provide.

Troubleshooting and tips

If you encounter token or API errors, verify that the GITLAB_PERSONAL_ACCESS_TOKEN has the required scopes and that GITLAB_API_URL points to the correct GitLab instance. Check that the Node process can reach the API URL and that the server process has the necessary filesystem permissions to read or modify files in the repository.

Examples of supported actions

Search for projects, read file contents, create or update a single file, push multiple files in one commit, create issues, create merge requests, fork a repository, and create branches. These actions are exposed as MCP tools that you can call from your AI assistant to automate common GitLab workflows.

Available tools

search_repositories

Search for GitLab projects by name, path, or keywords to discover relevant repositories.

get_file_contents

Fetch the contents of a file or list the contents of a directory within a repository.

create_or_update_file

Create a new file or update an existing file in a repository with specified content and commit message.

push_files

Push multiple files in a single commit to a repository, enabling batch updates.

create_repository

Create a new GitLab project/repository.

create_issue

Create a new issue in a GitLab project with title, description, and optional assignees.

create_merge_request

Create a new merge request (pull request) to propose changes from a branch into a target branch.

fork_repository

Fork an existing repository into your namespace.

create_branch

Create a new branch in a repository for isolated work.