# Gitlab Mcp

> A MCP server for GitLab with powerful, safe, policy-controlled access

- **Type:** MCP server
- **Install:** `agentstack add mcp-mcpland-gitlab-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [mcpland](https://agentstack.voostack.com/s/mcpland)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [mcpland](https://github.com/mcpland)
- **Source:** https://github.com/mcpland/gitlab-mcp

## Install

```sh
agentstack add mcp-mcpland-gitlab-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# gitlab-mcp

[](https://www.npmjs.com/package/gitlab-mcp)

A production-ready [MCP](https://modelcontextprotocol.io/) server for GitLab. Provides **80+ tools** that let AI assistants read and manage GitLab projects, merge requests, issues, pipelines, wikis, releases, and more through a unified, policy-controlled interface.

## Highlights

- **Comprehensive GitLab coverage** — projects, merge requests (with code-context analysis), issues, pipelines, wikis, milestones, releases, labels, commits, branches, GraphQL, and file management
- **Multiple transports** — stdio for local CLI usage, Streamable HTTP for remote deployments, optional SSE
- **Flexible authentication** — personal access tokens, OAuth 2.0 PKCE, external token scripts, token files, cookie-based auth, and per-request remote authorization
- **Policy engine** — read-only mode, tool allowlist/denylist, feature toggles, and project-scoped restrictions
- **Enterprise networking** — HTTP/HTTPS proxy, custom CA certificates, Cloudflare bypass, multi-instance API rotation
- **Output control** — JSON, compact JSON, or YAML formatting with configurable response size limits

## Usage

### Supported clients

Claude Desktop, Claude Code, VS Code, GitHub Copilot Chat (VS Code), Cursor, JetBrains AI Assistant, GitLab Duo, and any MCP client that supports stdio or streamable HTTP.

Current client format references:

- [MCP transports and protocol](https://modelcontextprotocol.io/docs/concepts/transports)
- [Claude Code MCP](https://docs.anthropic.com/en/docs/claude-code/mcp)
- [VS Code MCP servers](https://code.visualstudio.com/docs/copilot/customization/mcp-servers)
- [Cursor MCP](https://docs.cursor.com/context/model-context-protocol)
- [JetBrains AI Assistant MCP](https://www.jetbrains.com/help/ai-assistant/configure-an-mcp-server.html)

### Authentication methods

The server supports three auth patterns:

1. Personal Access Token (PAT)
2. OAuth 2.0 PKCE (recommended for local interactive use)
3. Remote per-request auth (`REMOTE_AUTHORIZATION=true`, HTTP mode)

### OAuth2 setup (stdio, recommended for local interactive use)

1. Create a GitLab OAuth application in `Settings -> Applications`.
2. Set redirect URI to `http://127.0.0.1:8765/callback` (or your custom callback).
3. Set scope to `api`.
4. Copy the Application ID as `GITLAB_OAUTH_CLIENT_ID`.

```json
{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "gitlab-mcp@latest"],
      "env": {
        "GITLAB_USE_OAUTH": "true",
        "GITLAB_OAUTH_CLIENT_ID": "your_oauth_client_id",
        "GITLAB_OAUTH_REDIRECT_URI": "http://127.0.0.1:8765/callback",
        "GITLAB_API_URL": "https://gitlab.com/api/v4",
        "GITLAB_ALLOWED_PROJECT_IDS": "",
        "GITLAB_READ_ONLY_MODE": "false",
        "USE_GITLAB_WIKI": "true",
        "USE_MILESTONE": "true",
        "USE_PIPELINE": "true"
      }
    }
  }
}
```

If your OAuth app is confidential, also set `GITLAB_OAUTH_CLIENT_SECRET`.

### Personal Access Token setup (stdio)

```json
{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "gitlab-mcp@latest"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
        "GITLAB_API_URL": "https://gitlab.com/api/v4",
        "GITLAB_ALLOWED_PROJECT_IDS": "",
        "GITLAB_READ_ONLY_MODE": "false",
        "USE_GITLAB_WIKI": "true",
        "USE_MILESTONE": "true",
        "USE_PIPELINE": "true"
      }
    }
  }
}
```

### VS Code `.vscode/mcp.json` examples

PAT with secure prompt input:

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "gitlab_token",
      "description": "GitLab Personal Access Token",
      "password": true
    }
  ],
  "servers": {
    "gitlab": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/gitlab-mcp/dist/index.js"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "${input:gitlab_token}",
        "GITLAB_API_URL": "https://gitlab.com/api/v4",
        "GITLAB_READ_ONLY_MODE": "false"
      }
    }
  }
}
```

OAuth (confidential app) with secure prompt input:

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "gitlab_oauth_secret",
      "description": "GitLab OAuth Client Secret",
      "password": true
    }
  ],
  "servers": {
    "gitlab": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/gitlab-mcp/dist/index.js"],
      "env": {
        "GITLAB_USE_OAUTH": "true",
        "GITLAB_OAUTH_CLIENT_ID": "your_oauth_client_id",
        "GITLAB_OAUTH_CLIENT_SECRET": "${input:gitlab_oauth_secret}",
        "GITLAB_OAUTH_REDIRECT_URI": "http://127.0.0.1:8765/callback",
        "GITLAB_API_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}
```

GitHub Copilot Chat in VS Code uses the same `.vscode/mcp.json` format.

### Claude Desktop / Claude Code / Cursor

Claude Desktop reads `claude_desktop_config.json`.
Claude Code supports project-level `.mcp.json` and `claude mcp add-json`.
Cursor uses `.cursor/mcp.json`.

```json
{
  "mcpServers": {
    "gitlab": {
      "command": "node",
      "args": ["/absolute/path/to/gitlab-mcp/dist/index.js"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
        "GITLAB_API_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}
```

### GitLab Duo (`~/.gitlab/duo/mcp.json`)

```json
{
  "mcpServers": {
    "gitlab": {
      "command": "node",
      "args": ["/absolute/path/to/gitlab-mcp/dist/index.js"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
        "GITLAB_API_URL": "https://gitlab.com/api/v4"
      }
    }
  },
  "approvedTools": ["gitlab_get_project", "gitlab_list_merge_requests"]
}
```

### JetBrains AI Assistant

JetBrains can import an existing MCP JSON config or register the server manually.
Use stdio command `node /absolute/path/to/gitlab-mcp/dist/index.js`, or HTTP endpoint `http://127.0.0.1:3333/mcp` with required headers.

### Remote authorization (multi-user HTTP)

Start server:

```bash
REMOTE_AUTHORIZATION=true \
HTTP_HOST=0.0.0.0 \
HTTP_PORT=3333 \
node dist/http.js
```

Client config:

```json
{
  "mcpServers": {
    "gitlab": {
      "url": "http://127.0.0.1:3333/mcp",
      "headers": {
        "Authorization": "Bearer glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

Dynamic per-request API URL:

```bash
REMOTE_AUTHORIZATION=true \
ENABLE_DYNAMIC_API_URL=true \
HTTP_HOST=0.0.0.0 \
HTTP_PORT=3333 \
node dist/http.js
```

Add header in client requests:

```json
{
  "headers": {
    "Authorization": "Bearer glpat-xxxxxxxxxxxxxxxxxxxx",
    "X-GitLab-API-URL": "https://gitlab.example.com/api/v4"
  }
}
```

Remote auth behavior matrix:

| Server Mode                                                 | Required Request Headers                                                                      | Token Fallback Chain |
| ----------------------------------------------------------- | --------------------------------------------------------------------------------------------- | -------------------- |
| `REMOTE_AUTHORIZATION=false` on local HTTP bind only        | none                                                                                          | enabled              |
| `REMOTE_AUTHORIZATION=true`                                 | `Authorization: Bearer `, `Private-Token: `, or `Job-Token: `            | disabled             |
| `REMOTE_AUTHORIZATION=true` + `ENABLE_DYNAMIC_API_URL=true` | `Authorization`, `Private-Token`, or `Job-Token`, and `X-GitLab-API-URL: https://host/api/v4` | disabled             |

When `HTTP_HOST` is not `127.0.0.1`, `localhost`, or `::1`, HTTP startup rejects
server-side `GITLAB_PERSONAL_ACCESS_TOKEN` or `GITLAB_JOB_TOKEN` unless
`REMOTE_AUTHORIZATION=true`.

### Docker

For containerized deployments, PAT or remote auth is recommended.
OAuth interactive callback flow is usually less convenient in containers.

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

or:

```bash
docker build -t gitlab-mcp .

docker run -d \
  --name gitlab-mcp \
  -p 3333:3333 \
  -e GITLAB_API_URL=https://gitlab.com/api/v4 \
  -e GITLAB_PERSONAL_ACCESS_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx \
  gitlab-mcp
```

### Compatibility notes

- `GITLAB_PROJECT_ID` is not a supported environment variable in this repository.
- To set an effective default project, use `GITLAB_ALLOWED_PROJECT_IDS` with one project ID, or pass `project_id` in tool arguments.
- CLI argument overrides such as `--token` or `--api-url` are not implemented (`--env-file` is supported).
- JSON config files do not support comments (`//`).

## MCP Server Configuration

## HTTP server

```bash
pnpm install
cp .env.example .env
pnpm build

# stdio (local MCP)
pnpm start

# streamable HTTP server (http://127.0.0.1:3333/mcp)
pnpm start:http

# optional: load a specific env file
pnpm start -- --env-file .env.local
pnpm start:http -- --env-file .env.local
```

### Transport and entrypoint

| Transport           | Entry Point          | Endpoint                     | Best For                             |
| ------------------- | -------------------- | ---------------------------- | ------------------------------------ |
| **stdio**           | `node dist/index.js` | stdin/stdout                 | Local single-user MCP clients        |
| **Streamable HTTP** | `node dist/http.js`  | `POST/GET/DELETE /mcp`       | Remote/shared deployments            |
| **SSE (legacy)**    | `node dist/http.js`  | `GET /sse`, `POST /messages` | Legacy SSE-only clients (`SSE=true`) |
| **Health**          | `node dist/http.js`  | `GET /healthz`               | Liveness/readiness checks            |

`SSE=true` is not compatible with `REMOTE_AUTHORIZATION=true`.

## Tool Categories

Tools are organized into these categories. All GitLab tools use the `gitlab_` prefix, except `health_check`.

| Category            | Examples                                                                    | Count |
| ------------------- | --------------------------------------------------------------------------- | ----- |
| **Projects**        | `get_project`, `list_projects`, `create_repository`, `fork_repository`      | 8     |
| **Repository**      | `get_repository_tree`, `get_file_contents`, `push_files`, `create_branch`   | 7     |
| **Merge Requests**  | `list_merge_requests`, `get_merge_request_conflicts`, `merge_merge_request` | 13    |
| **MR Code Context** | `get_merge_request_code_context` (advanced code review)                     | 1     |
| **MR Discussions**  | `list_merge_request_discussions`, `create_merge_request_thread`             | 7     |
| **MR Notes**        | `list_merge_request_notes`, `create_merge_request_note`                     | 7     |
| **Draft Notes**     | `list_draft_notes`, `create_draft_note`, `bulk_publish_draft_notes`         | 7     |
| **Issues**          | `list_issues`, `create_issue`, `update_issue`, issue links                  | 13    |
| **Pipelines**       | `list_pipelines`, `list_deployments`, `get_job_artifact_file_inline`        | 20    |
| **Commits**         | `list_commits`, `get_commit`, `get_commit_diff`                             | 3     |
| **Labels**          | `list_labels`, `create_label`, `update_label`                               | 5     |
| **Milestones**      | `list_milestones`, `create_milestone`, burndown events                      | 10    |
| **Releases**        | `list_releases`, `create_release`, `download_release_asset`                 | 7     |
| **Wiki**            | `list_wiki_pages`, `create_wiki_page`, `update_wiki_page`                   | 5     |
| **Uploads**         | `upload_markdown`, `download_attachment`                                    | 2     |
| **GraphQL**         | `execute_graphql_query`, `execute_graphql_mutation`                         | 3     |
| **Users & Groups**  | `get_users`, `list_namespaces`, `list_events`                               | 6     |
| **Health**          | `health_check`                                                              | 1     |

See [docs/tools.md](docs/tools.md) for the complete reference.

## Policy & Security

The policy engine controls which tools are available at registration time:

```bash
# Read-only mode — disables write/delete/admin capabilities
GITLAB_READ_ONLY_MODE=true

# Disable specific capability classes without going fully read-only
GITLAB_DISABLED_CAPABILITIES=delete,graphql

# Only expose specific tools (supports with or without gitlab_ prefix)
GITLAB_ALLOWED_TOOLS=get_project,list_merge_requests,get_merge_request

# Block tools by regex pattern
GITLAB_DENIED_TOOLS_REGEX=^gitlab_(delete|create)_

# Restrict to specific projects
GITLAB_ALLOWED_PROJECT_IDS=123,456,789

# Keep GraphQL tools enabled in project-scoped mode (disabled by default)
GITLAB_ALLOW_GRAPHQL_WITH_PROJECT_SCOPE=true

# Disable feature groups
USE_PIPELINE=false
USE_GITLAB_WIKI=false
```

Unsafe or invalid `GITLAB_DENIED_TOOLS_REGEX` patterns fail startup.

## Configuration

All configuration is done through environment variables. Key settings:

For file-based loading, `.env` is loaded by default. You can override it with:

```bash
node dist/index.js --env-file .env.local
node dist/http.js --env-file=.env.production
```

| Area            | Variable                                  | Default                     | Description                                                                              |
| --------------- | ----------------------------------------- | --------------------------- | ---------------------------------------------------------------------------------------- |
| GitLab API      | `GITLAB_API_URL`                          | `https://gitlab.com/api/v4` | Base API URL. Supports comma-separated multi-instance URLs.                              |
| GitLab API      | `GITLAB_PERSONAL_ACCESS_TOKEN`            | —                           | Static default token used when `REMOTE_AUTHORIZATION=false`.                             |
| GitLab API      | `GITLAB_JOB_TOKEN`                        | —                           | Static CI job token fallback when no personal access token is configured.                |
| Remote Auth     | `REMOTE_AUTHORIZATION`                    | `false`                     | Require per-request token headers in HTTP mode (disables fallback token chain).          |
| Remote Auth     | `ENABLE_DYNAMIC_API_URL`                  | `false`                     | Require `X-GitLab-API-URL` per request. Requires `REMOTE_AUTHORIZATION=true`.            |
| Remote Auth     | `GITLAB_MCP_OAUTH`                        | `false`                     | Enable MCP OAuth discovery/proxy endpoints for HTTP mode. Requires `MCP_SERVER_URL`.     |
| HTTP Server     | `HTTP_HOST`                               | `127.0.0.1`                 | HTTP bind host (`0.0.0.0` for external access).                                          |
| HTTP Server     | `HTTP_PORT`                               | `3333`                      | HTTP server port.                                                                        |
| HTTP Server     | `MCP_SERVER_URL`                          | —                           | Public base URL used when HTTP download tools return proxy URLs.                         |
| HTTP Server     | `HTTP_JSON_ONLY`                          | `false`                     | Force JSON-only responses (no streaming framing).                                        |
| HTTP Server     | `SSE`                                     | `false`                     | Enable legacy SSE endpoints (`/sse`, `/messages`). Not compatible with remote auth.      |
| Sessions        | `SESSION_TIMEOUT_SECONDS`                 | `3600`                      | Idle session timeout in HTTP mode.                                                       |
| Sessions        | `OAUTH_STATELESS_MODE`                    | `false`                     | Use stateless Streamable HTTP transports; cl

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [mcpland](https://github.com/mcpland)
- **Source:** [mcpland/gitlab-mcp](https://github.com/mcpland/gitlab-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-mcpland-gitlab-mcp
- Seller: https://agentstack.voostack.com/s/mcpland
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.