convez.ai
MCP ServerDevOps & InfraestruturaIntermediário
mcpland

GitLab MCP Server

mcpland/gitlab-mcp

Integração completa GitLab com 80+ tools para IA gerenciar projetos e CI/CD

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor MCP production-ready que expõe 80+ ferramentas para leitura e gerenciamento de projetos GitLab, merge requests, issues, pipelines e wikis através de uma interface unificada com controle de políticas. Suporta múltiplos transportes (stdio, HTTP Streamable, SSE) e autenticação flexível (tokens, OAuth 2.0, auth remoto).

Instalação

$npx convez-ai mcpland/gitlab-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
10
Forks
9
Acompanhando
1
Saúde
37%
Último commit
há 6 dias
Versão
v1.7.0
Issues abertas
2
Contribuidores
3

Casos de uso

  • Automatizar gerenciamento de merge requests e code review com contexto de código
  • Consultar issues, pipelines e status de CI/CD via assistente IA
  • Executar operações de repositório (commits, branches, releases) programaticamente
  • Monitorar wikis, milestones e labels em GitLab Enterprise com restrições por projeto

Veredito

Ferramenta madura e bem documentada para integrar GitLab com agentes IA. Cobertura ampla (80+ operações), suporte enterprise (proxy, multi-instância, policy engine) e flexibilidade de autenticação a tornam sólida, mas exige conhecimento técnico moderado para configuração OAuth e transporte HTTP em produção.

README

A tradução para o português deste README ainda está na fila.

gitlab-mcp

Node CI npm license

A production-ready MCP 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:

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.
{
  "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)

{
  "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:

{
  "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:

{
  "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.

{
  "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)

{
  "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:

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

Client config:

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

Dynamic per-request API URL:

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:

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

Remote auth behavior matrix:

Server ModeRequired Request HeadersToken Fallback Chain
REMOTE_AUTHORIZATION=false on local HTTP bind onlynoneenabled
REMOTE_AUTHORIZATION=trueAuthorization: Bearer <token>, Private-Token: <token>, or Job-Token: <token>disabled
REMOTE_AUTHORIZATION=true + ENABLE_DYNAMIC_API_URL=trueAuthorization, Private-Token, or Job-Token, and X-GitLab-API-URL: https://host/api/v4disabled

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.

docker compose up --build -d

or:

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

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

TransportEntry PointEndpointBest For
stdionode dist/index.jsstdin/stdoutLocal single-user MCP clients
Streamable HTTPnode dist/http.jsPOST/GET/DELETE /mcpRemote/shared deployments
SSE (legacy)node dist/http.jsGET /sse, POST /messagesLegacy SSE-only clients (SSE=true)
Healthnode dist/http.jsGET /healthzLiveness/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.

CategoryExamplesCount
Projectsget_project, list_projects, create_repository, fork_repository8
Repositoryget_repository_tree, get_file_contents, push_files, create_branch7
Merge Requestslist_merge_requests, get_merge_request_conflicts, merge_merge_request13
MR Code Contextget_merge_request_code_context (advanced code review)1
MR Discussionslist_merge_request_discussions, create_merge_request_thread7
MR Noteslist_merge_request_notes, create_merge_request_note7
Draft Noteslist_draft_notes, create_draft_note, bulk_publish_draft_notes7
Issueslist_issues, create_issue, update_issue, issue links13
Pipelineslist_pipelines, list_deployments, get_job_artifact_file_inline20
Commitslist_commits, get_commit, get_commit_diff3
Labelslist_labels, create_label, update_label5
Milestoneslist_milestones, create_milestone, burndown events10
Releaseslist_releases, create_release, download_release_asset7
Wikilist_wiki_pages, create_wiki_page, update_wiki_page5
Uploadsupload_markdown, download_attachment2
GraphQLexecute_graphql_query, execute_graphql_mutation3
Users & Groupsget_users, list_namespaces, list_events6
Healthhealth_check1

See docs/tools.md for the complete reference.

Policy & Security

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

# 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:

node dist/index.js --env-file .env.local
node dist/http.js --env-file=.env.production
AreaVariableDefaultDescription
GitLab APIGITLAB_API_URLhttps://gitlab.com/api/v4Base API URL. Supports comma-separated multi-instance URLs.
GitLab APIGITLAB_PERSONAL_ACCESS_TOKEN—Static default token used when REMOTE_AUTHORIZATION=false.
GitLab APIGITLAB_JOB_TOKEN—Static CI job token fallback when no personal access token is configured.
Remote AuthREMOTE_AUTHORIZATIONfalseRequire per-request token headers in HTTP mode (disables fallback token chain).
Remote AuthENABLE_DYNAMIC_API_URLfalseRequire X-GitLab-API-URL per request. Requires REMOTE_AUTHORIZATION=true.
Remote AuthGITLAB_MCP_OAUTHfalseEnable MCP OAuth discovery/proxy endpoints for HTTP mode. Requires MCP_SERVER_URL.
HTTP ServerHTTP_HOST127.0.0.1HTTP bind host (0.0.0.0 for external access).
HTTP ServerHTTP_PORT3333HTTP server port.
HTTP ServerMCP_SERVER_URL—Public base URL used when HTTP download tools return proxy URLs.
HTTP ServerHTTP_JSON_ONLYfalseForce JSON-only responses (no streaming framing).
HTTP ServerSSEfalseEnable legacy SSE endpoints (/sse, /messages). Not compatible with remote auth.
SessionsSESSION_TIMEOUT_SECONDS3600Idle session timeout in HTTP mode.
SessionsOAUTH_STATELESS_MODEfalseUse stateless Streamable HTTP transports; clients must send auth on every request.
SessionsMAX_SESSIONS1000Maximum concurrent sessions (503 when reached).
SessionsMAX_REQUESTS_PER_MINUTE300Per-session rate limit (429 when exceeded).
PolicyGITLAB_READ_ONLY_MODEfalseDisable tools that require write, delete, or admin capabilities.
PolicyGITLAB_ALLOWED_PROJECT_IDS—Restrict access to specific GitLab project IDs.
PolicyGITLAB_ALLOWED_TOOLS—Tool allowlist (supports names with or without gitlab_ prefix).
PolicyGITLAB_DISABLED_CAPABILITIES—Capability denylist. Valid values: read, write, delete, admin, graphql.
PolicyGITLAB_DENIED_TOOLS_REGEX—Regex denylist for tool names.
PolicyGITLAB_ALLOW_GRAPHQL_WITH_PROJECT_SCOPEfalseKeep GraphQL tools enabled when project scope restriction is active.
Auth ExtensionsGITLAB_USE_OAUTHfalseEnable OAuth 2.0 PKCE flow.
Auth ExtensionsGITLAB_OAUTH_SCOPESmode-dependentOAuth scopes advertised/requested by local OAuth and MCP OAuth.
Auth ExtensionsGITLAB_TOKEN_SCRIPT—Resolve token from an external script.
Auth ExtensionsGITLAB_TOKEN_FILE—Resolve token from a local file.
Auth ExtensionsGITLAB_AUTH_COOKIE_PATH—Enable cookie-jar based session auth from Netscape cookie file.
OutputGITLAB_RESPONSE_MODEjsonResponse format: json, compact-json, yaml.
OutputGITLAB_MAX_RESPONSE_BYTES200000Max response payload (1KB–2MB), oversized payloads are truncated safely.
OutputGITLAB_MAX_LOCAL_FILE_BYTES250000000Max size for files saved locally by download tools such as job artifacts.
OutputGITLAB_DOWNLOAD_TOKEN_SECRETrandom per processSecret for short-lived HTTP download proxy URLs; set this for multi-replica deployments.
OutputGITLAB_DOWNLOAD_TOKEN_TTL_SECONDS300Lifetime of generated HTTP download proxy URLs.
OutputGITLAB_HTTP_TIMEOUT_MS20000Upstream GitLab HTTP timeout (1s–120s).
OutputGITLAB_ERROR_DETAIL_MODEsafe/fullError verbosity (safe by default in production, full otherwise).
Network/TLSHTTP_PROXY, HTTPS_PROXY, NO_PROXY—Proxy settings for outbound GitLab requests, including per-host proxy bypass rules.
Network/TLSGITLAB_CA_CERT_PATH—Custom CA certificate path (PEM).
Network/TLSGITLAB_CLOUDFLARE_BYPASSfalseAdd browser-like headers for Cloudflare-protected instances.
Network/TLSGITLAB_USER_AGENT—Custom User-Agent for GitLab requests.

See docs/configuration.md for the complete reference.

Authentication Methods

Authentication behavior depends on mode:

  1. REMOTE_AUTHORIZATION=true (HTTP strong mode) Each request must include Authorization: Bearer <token>, Private-Token: <token>, or Job-Token: <token>. When ENABLE_DYNAMIC_API_URL=true, each request must also include X-GitLab-API-URL.
  2. REMOTE_AUTHORIZATION=false (default mode) The server resolves credentials in this order: GITLAB_PERSONAL_ACCESS_TOKEN -> GITLAB_JOB_TOKEN -> OAuth PKCE (GITLAB_USE_OAUTH=true) -> GITLAB_TOKEN_SCRIPT -> GITLAB_TOKEN_FILE.

Cookie-based auth (GITLAB_AUTH_COOKIE_PATH) is applied independently via a cookie jar and can work with or without a token.

See docs/authentication.md for setup guides.

Development

pnpm dev           # stdio mode with hot-reload
pnpm dev:http      # HTTP mode with hot-reload
pnpm test          # Run tests
pnpm test:watch    # Run tests in watch mode
pnpm lint          # Lint
pnpm typecheck     # Type check
pnpm inspector     # Launch MCP Inspector

Project Structure

See docs/architecture.md for detailed design documentation.

Documentation

Acknowledgements

This repository references and learns from parts of the implementation in zereight/gitlab-mcp. Thanks to the maintainers and contributors for their work.

License

MIT

Ver o original no GitHub

Bom para

Relacionados