GitLab MCP Server

How to use

You run the GitLab MCP Server locally or in your environment and connect to it from an MCP client. Start by configuring a server entry that uses the MCP command to run the GitLab MCP package. Choose OAuth for secure access or a personal access token for simpler setups.

How to install

Prerequisites: you need Node.js and npm installed on your machine.

Install the MCP package globally so you can run it from any location.

npm install -g @anupsahu/gitlab-mcp

Create a configuration that runs the MCP server using the package runner. You can use OAuth authentication or a personal access token. The following configurations use the standard npm/npx flow shown in examples.

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@anupsahu/gitlab-mcp"],
      "env": {
        "USE_OAUTH": "true",
        "GITLAB_API_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@anupsahu/gitlab-mcp"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "your_gitlab_token",
        "GITLAB_API_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}

Additional configuration and usage notes

OAuth authentication uses PKCE for secure access. Start the server with OAuth enabled and follow the login flow through the provided OAuth tool set. Tokens are automatically saved and survive server restarts.

Important port note: the OAuth callback uses http://localhost:7171 for compatibility with GitLab’s OAuth apps. Ensure port 7171 is free during authentication.

Automatic token refresh keeps your sessions valid without manual intervention.

Configuration

Environment variables you can set to customize behavior:

USE_OAUTH
GITLAB_API_URL
GITLAB_PERSONAL_ACCESS_TOKEN
GITLAB_PROJECT_ID
GITLAB_ALLOWED_PROJECT_IDS
GITLAB_READ_ONLY_MODE
OAUTH_REDIRECT_PORT_PREFERRED
OAUTH_REDIRECT_PORT_RANGE

Examples of common operations (via MCP client)

The MCP server exposes a range of operations to manage repositories, merge requests, issues, commits, and branches. You can perform search, read, create, update, and merge actions against GitLab resources through the MCP client. Use the same session for multiple requests and rely on token persistence to avoid re-authentication.

Security and best practices

Use OAuth for production deployments to avoid exposing long-lived tokens. Enable token persistence per your security policy and rely on automatic token refresh to maintain seamless access.

Troubleshooting

If you encounter authentication failures, check that OAuth is enabled and that port 7171 is open for the callback. Verify that your GITLAB_API_URL points to the correct GitLab instance and that tokens (OAuth or PAT) are valid.

oauth_login_pkce

Initiate OAuth authentication flow using PKCE to obtain tokens.

oauth_status

Check the current authentication status and token validity.

oauth_logout

Logout and clear stored OAuth tokens.

search_repositories

Search for GitLab repositories accessible to the authenticated user.

get_repository_tree

Retrieve the repository file tree for navigation.

get_file_contents

Read the contents of a file in a repository.

create_or_update_file

Create or update a file in a repository.

push_files

Push multiple file changes to a repository.

get_merge_request

Get details of a merge request.

get_merge_request_diffs

Get the diffs for a merge request.

create_merge_request

Create a new merge request.

update_merge_request

Update an existing merge request.

merge_merge_request

Merge a merge request.

create_issue

Create a new issue in a project.

get_issue

Get details of an issue.

update_issue

Update an existing issue.

list_issues

List issues in a project.

list_commits

List repository commits.

get_commit

Get details for a specific commit.

get_commit_diff

Get the diff for a commit.

create_branch

Create a new branch in the repository.

fork_repository

Fork a repository into another namespace.