GitLab MCP Server

https://github.com/zereight/gitlab-mcp
Admin
GitLab MCP Server is a comprehensive Model Context Protocol server that enables AI clients to manage...
Tokens:247,783
Snippets:1,675
Trust Score:8.8
License:MIT
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### Example Configuration - Local Single PAT

Source: https://github.com/zereight/gitlab-mcp/blob/main/docs/auth/custom-agent-multiple-pat.md

Example configuration for a local single-PAT setup.

```bash
GITLAB_PERSONAL_ACCESS_TOKEN=glpat-local-user \
GITLAB_API_URL=https://gitlab.com/api/v4 \
zereight-mcp-gitlab
```

--------------------------------

### Example MCP configuration with CLI arguments

Source: https://github.com/zereight/gitlab-mcp/blob/main/docs/getting-started/cli-arguments.md

Example JSON configuration for an MCP client that uses the installed server with CLI arguments for token and API URL.

```json
{
  "mcpServers": {
    "gitlab": {
      "command": "zereight-mcp-gitlab",
      "args": ["--token=YOUR_GITLAB_TOKEN", "--api-url=https://gitlab.com/api/v4"],
      "tools": ["*"]
    }
  }
}
```

--------------------------------

### Install via Homebrew

Source: https://github.com/zereight/gitlab-mcp/blob/main/docs/clients/copilot.md

Install the MCP server using Homebrew. Requires the tap zereight/gitlab-mcp.

```bash
brew tap zereight/gitlab-mcp https://github.com/zereight/gitlab-mcp
brew install zereight/gitlab-mcp/zereight-mcp-gitlab
```

--------------------------------

### Install via npm

Source: https://github.com/zereight/gitlab-mcp/blob/main/docs/clients/copilot.md

Install the MCP server globally using npm.

```bash
npm install -g @zereight/mcp-gitlab
```

--------------------------------

### Clone, install, and build the project

Source: https://github.com/zereight/gitlab-mcp/blob/main/docs/contributing.md

Sets up the project locally: clones the repository, switches to the pinned Node version with nvm, installs dependencies, and compiles TypeScript to the build/ directory.

```bash
git clone https://github.com/zereight/gitlab-mcp.git
cd gitlab-mcp
nvm use            # or: nvm install
npm install
npm run build      # compiles TypeScript to build/
```

--------------------------------

### Example Configuration - Hosted Multi-User HTTP Server

Source: https://github.com/zereight/gitlab-mcp/blob/main/docs/auth/custom-agent-multiple-pat.md

Example configuration for a hosted multi-user HTTP server with remote authorization and session timeout.

```bash
STREAMABLE_HTTP=true \
REMOTE_AUTHORIZATION=true \
SESSION_TIMEOUT_SECONDS=3600 \
GITLAB_API_URL=https://gitlab.com/api/v4 \
zereight-mcp-gitlab
```

--------------------------------

### Install GitLab MCP Server

Source: https://github.com/zereight/gitlab-mcp/blob/main/docs/clients/claude-code.md

Install the server using Homebrew or npm. If the command is not found, use the absolute path from 'which zereight-mcp-gitlab'.

```bash
brew tap zereight/gitlab-mcp https://github.com/zereight/gitlab-mcp
brew install zereight/gitlab-mcp/zereight-mcp-gitlab
```

```bash
npm install -g @zereight/mcp-gitlab
```

--------------------------------

### mcpServers wrapper example

Source: https://github.com/zereight/gitlab-mcp/blob/main/docs/clients/json-clients.md

Example wrapper when the client expects an mcpServers object. Places the PAT server block inside the wrapper.

```json
{
  "mcpServers": {
    "gitlab": {
      "command": "zereight-mcp-gitlab",
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-your-token",
        "GITLAB_API_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}
```

--------------------------------

### servers wrapper example

Source: https://github.com/zereight/gitlab-mcp/blob/main/docs/clients/json-clients.md

Example wrapper when the client expects a servers object. Includes type stdio and places the PAT server block inside.

```json
{
  "servers": {
    "gitlab": {
      "type": "stdio",
      "command": "zereight-mcp-gitlab",
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-your-token",
        "GITLAB_API_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}
```

--------------------------------

### Install GitLab MCP skill with npx

Source: https://github.com/zereight/gitlab-mcp/blob/main/README.md

Use this command to install the pre-built GitLab MCP skill files for AI agents that support skill loading. Requires Node.js and npx.

```bash
npx skills add zereight/gitlab-mcp --skill gitlab-mcp-skill
```

--------------------------------

### X-GitLab-Allowed-Project-Ids header example

Source: https://github.com/zereight/gitlab-mcp/blob/main/docs/configuration/environment-variables.md

Example HTTP headers showing how to narrow project scope per session using the X-GitLab-Allowed-Project-Ids header. Requires REMOTE_AUTHORIZATION=true and ENABLE_DYNAMIC_PROJECT_SCOPE=true. The header can only narrow, never widen, and entries must match configured values verbatim.

```http
X-GitLab-Allowed-Project-Ids: 42
Private-Token: glpat-xxxxxxxxxxxxxxxxxxxx
```

--------------------------------

### GITLAB_INSTANCES JSON configuration example

Source: https://github.com/zereight/gitlab-mcp/blob/main/docs/configuration/multi-instance-design.md

Example JSON array for the GITLAB_INSTANCES environment variable, defining two GitLab instance profiles: 'gitlab-com' with an inline token and 'corp' with a tokenEnv reference. Phase 1 is PAT-only.

```json
[
  {
    "id": "gitlab-com",
    "apiUrl": "https://gitlab.com/api/v4",
    "token": "glpat-xxxxxxxx"
  },
  {
    "id": "corp",
    "apiUrl": "https://gitlab.corp.example.com/api/v4",
    "tokenEnv": "GITLAB_CORP_PAT"
  }
]
```

--------------------------------

### Example Configuration - Restricted Agent

Source: https://github.com/zereight/gitlab-mcp/blob/main/docs/auth/custom-agent-multiple-pat.md

Example configuration for a restricted agent that exposes issue, merge request, and project tools while hiding destructive operations and requiring confirmation for selected write tools.

```bash
STREAMABLE_HTTP=true \
REMOTE_AUTHORIZATION=true \
GITLAB_TOOLSETS=issues,merge_requests,projects \
GITLAB_DENIED_TOOLS_REGEX="^(delete_|merge_)" \
GITLAB_TOOL_POLICY_APPROVE="create_issue,update_issue,create_merge_request" \
zereight-mcp-gitlab
```

--------------------------------

### get_merge_request_version

Source: https://github.com/zereight/gitlab-mcp/blob/main/docs/tools/index.md

Get a specific version of a merge request. Use this when you know the version you want to inspect.

```APIDOC
## get_merge_request_version

### Description
Get a specific version of a merge request. Read-only operation; does not mutate GitLab data.

### Parameters
- `mergeRequestIid` (required) - The IID of the merge request.
- `version_id` (required) - The ID of the specific version.
- `project_id` (optional) - Numeric ID or URL-encoded path of the project.
- `group_id` (optional) - Numeric ID or URL-encoded path of the group.

### Response
Returns the requested version. Errors for missing resources, invalid identifiers, insufficient permission, and rate limits.
```

--------------------------------

### Preview and build documentation with make commands

Source: https://github.com/zereight/gitlab-mcp/blob/main/docs/contributing.md

Run 'make serve' to preview locally, 'make build' for strict build, and 'make tools-docs' to regenerate tool pages.

```bash
make serve         # preview locally at http://127.0.0.1:8000/gitlab-mcp/
make build         # strict build (same as CI)
make tools-docs    # regenerate tool pages + docs/reference/tool-coverage.md

```

--------------------------------

### GitLab CI Configuration for Test Suite

Source: https://github.com/zereight/gitlab-mcp/blob/main/test/README.md

Example GitLab CI configuration that installs dependencies, builds, and runs the test suite. Uses CI-provided variables for authentication and project ID.

```yaml
# Example GitLab CI configuration
test:
  script:
    - npm install
    - npm run build
    - npm run test:all
  variables:
    GITLAB_PERSONAL_ACCESS_TOKEN: $CI_JOB_TOKEN
    GITLAB_PROJECT_ID: $CI_PROJECT_ID
```

--------------------------------

### Recommended first prompt

Source: https://github.com/zereight/gitlab-mcp/blob/main/docs/clients/copilot.md

A recommended prompt to try after setup to list projects and recent merge requests.

```text
Show me my GitLab projects and recent merge requests.
```

--------------------------------

### Copy environment variables from example

Source: https://github.com/zereight/gitlab-mcp/blob/main/docker/README.md

Run from the root `docker` directory. Copies `.env.example` to `.env` to set up the environment variables.

```bash
cd docker

cp .env.example .env
```

--------------------------------

### Invalid example: Both parameters

Source: https://github.com/zereight/gitlab-mcp/blob/main/docs/features/resolve-issue-thread.md

Example of an invalid request providing both body and resolved parameters, which triggers a validation error.

```json
{ "body": "New content", "resolved": true }
```

--------------------------------

### Invalid example: No parameters

Source: https://github.com/zereight/gitlab-mcp/blob/main/docs/features/resolve-issue-thread.md

Example of an invalid request missing both body and resolved parameters, which triggers a validation error.

```json
{}
```

--------------------------------

### Start the server with Docker Compose

Source: https://github.com/zereight/gitlab-mcp/blob/main/docker/README.md

Starts the GitLab MCP server in detached mode using the configured Docker Compose environment.

```bash
docker compose up -d
```

--------------------------------

### List, Get, Delete Issue Links

Source: https://github.com/zereight/gitlab-mcp/blob/main/skills/gitlab-mcp/reference/issues.md

Operations to list all linked issues, get specific link details, and remove a link.

```plaintext
list_issue_links   -> list all linked issues
get_issue_link     -> get specific link details
delete_issue_link  -> remove a link
```

--------------------------------

### Local preview commands for MkDocs site

Source: https://github.com/zereight/gitlab-mcp/blob/main/docs/reference/github-pages-setup.md

Local preview commands for the MkDocs site. `make serve` starts a local server at http://127.0.0.1:8000/gitlab-mcp/ and `make build` performs a strict build identical to the CI process.

```bash
make serve    # http://127.0.0.1:8000/gitlab-mcp/
```

```bash
make build    # strict build, same as CI
```

--------------------------------

### Show Auth Command Help

Source: https://github.com/zereight/gitlab-mcp/blob/main/docs/auth/oauth-setup.md

Displays help information for the auth command, including available options and usage.

```bash
zereight-mcp-gitlab auth --help
```

--------------------------------

### Multiple GitLab Instances Setup

Source: https://github.com/zereight/gitlab-mcp/blob/main/docs/auth/custom-agent-multiple-pat.md

Enables dynamic API URL support so one server can connect to different GitLab instances. The header host must match GITLAB_API_URL or GITLAB_ALLOWED_HOSTS.

```bash
STREAMABLE_HTTP=true \
REMOTE_AUTHORIZATION=true \
ENABLE_DYNAMIC_API_URL=true \
GITLAB_ALLOWED_HOSTS=gitlab.example.com \
zereight-mcp-gitlab
```

--------------------------------

### Managed policy reference JSON example

Source: https://github.com/zereight/gitlab-mcp/blob/main/docs/configuration/environment-variables.md

Example of a version 2 managed-policy reference that can be placed in the masking configuration file. Requires GITLAB_MASKING_POLICY_FILE to be set.

```json
{ "version": 2, "mode": "managed", "policyGroup": "team-default" }
```

--------------------------------

### Recommended first prompt

Source: https://github.com/zereight/gitlab-mcp/blob/main/docs/clients/codex.md

Recommended first prompt to test the GitLab MCP server.

```text
List my GitLab projects and recent merge requests.
```

--------------------------------

### Tool Customization Setup

Source: https://github.com/zereight/gitlab-mcp/blob/main/docs/auth/custom-agent-multiple-pat.md

Exposes only the tools needed by custom agents using GITLAB_TOOLSETS, GITLAB_TOOLS, and GITLAB_DENIED_TOOLS_REGEX.

```bash
GITLAB_TOOLSETS=issues,merge_requests,projects \
GITLAB_TOOLS=get_file_contents \
GITLAB_DENIED_TOOLS_REGEX="^(delete_|merge_)" \
zereight-mcp-gitlab
```

--------------------------------

### Commit message examples

Source: https://github.com/zereight/gitlab-mcp/blob/main/docs/contributing.md

Examples of commit message prefixes matching branch types: feat, fix, docs, chore. Short, present-tense, lowercase. Changelog generator groups by these prefixes.

```plaintext
feat: add list_dependency_proxy_blobs tool
fix: handle 429 rate-limit on get_merge_request
docs: clarify OAuth redirect URI for Cursor

```
Tokens:
Raw