DOCSEARCHbyAlgolia
Submit Docs

GitLab MCP Server

repository·main·Indexed 23 days ago

https://github.com/zereight/gitlab-mcp

A Model Context Protocol (MCP) server that provides AI agents with a standardized interface to interact with the GitLab API. It enables automated management of projects, issues, merge requests, CI/CD pipelines, wikis, and releases. The server supports multiple transport methods including SSE and Streamable HTTP, and offers advanced authentication modes such as Remote Authorization for multi-user deployments and an OAuth proxy for native Claude.ai integration.

Tokens
71.3K
Snippets
111
Records
408
Agent score
79%

What's inside @zereight/mcp-gitlab

  1. Overview of @zereight/mcp-gitlab

    main

    The @zereight/mcp-gitlab package is a comprehensive Model Context Protocol (MCP) server designed for AI clients to interact with GitLab. It enables management of various GitLab resources including projects, merge requests, issues, pipelines, wikis, releases, and milestones.

    Key Capabilities:

    • Broad GitLab Support: Manage repositories, issues, merge requests, pipelines, wikis, releases, labels, and milestones.
    • Flexible Authentication: Supports Personal Access Tokens (PAT), local OAuth2 browser flows, MCP OAuth proxies, and per-request remote authentication.
    • Multiple Transport Protocols: Supports stdio (for local clients), SSE (for legacy clients), and Streamable HTTP (for modern remote deployments).
    • Self-Hosting Ready: Supports custom GitLab instances, proxy configurations, and dynamic API URL routing.
    • Client Compatibility: Works with VS Code, Claude, Cursor, Copilot, and other MCP-compatible clients.

  2. Overview of Work Items tools

    main

    The Work Items toolset provides a unified API for interacting with typed work items in GitLab, such as issues, tasks, and incidents. It also supports managing associated metadata like notes, emoji reactions, and incident timeline events.

    Available tools in this group include:

    • get_work_item
    • list_work_items
    • create_work_item
    • update_work_item
    • convert_work_item_type
    • list_work_item_statuses
    • list_custom_field_definitions
    • move_work_item
    • list_work_item_notes
    • create_work_item_note

  3. Manage GitLab issues with the Issues toolset

    main
    The Issues toolset in the GitLab MCP server provides full CRUD (Create, Read, Update, Delete) capabilities for GitLab issues. It also supports managing issue-related metadata such as discussions, notes, todos, and emoji reactions. This group of tools allows an AI agent or developer to programmatically interact with the lifecycle of an issue within a GitLab project.

  4. Understand GitLab MCP tool capabilities

    main

    When browsing the tools reference, look for the following markers to understand the impact of a tool call:

    • 📖 Read-only: The tool fetches data and does not modify the state of GitLab. These are safe to invoke without caution.
    • ✏️ Writes: The tool creates, updates, or deletes data on GitLab. You should confirm your intent before allowing these tools to run.

  5. How Remote Authorization works (Multi-user support)

    main

    When REMOTE_AUTHORIZATION=true is enabled, the MCP server supports multiple users by having each caller provide their own GitLab token in the HTTP request headers. This is ideal for shared server instances where users want to use their own GitLab permissions.

    Authentication Header Priority:

    1. Private-Token (GitLab Personal Access Token)
    2. JOB-TOKEN (GitLab CI Job Token)
    3. Authorization: Bearer (OAuth token)

    Key Characteristics:

    • Transport: Must use STREAMABLE_HTTP=true. SSE is not compatible.
    • Isolation: Each session is isolated. A token from one session cannot access data from another.
    • Session Timeout: Tokens expire after SESSION_TIMEOUT_SECONDS (default 1 hour) of inactivity. Each request resets the timer.
    • Rate Limiting: Requests are limited by client IP (MAX_REQUESTS_PER_MINUTE) and by MCP session (default 60).

    Example Client Header:

    Authorization: Bearer glpat-xxxxxxxxxxxxxxxxxxxx

    Example Docker Setup:

    docker run -d \
  -e HOST=0.0.0.0 \
  -e STREAMABLE_HTTP=true \
  -e REMOTE_AUTHORIZATION=true \
  -e GITLAB_API_URL="https://gitlab.com/api/v4" \
  -e GITLAB_PERMISSION_MODE=readonly \
  -e SESSION_TIMEOUT_SECONDS=3600 \
  -p 3333:3002 \
  zereight050/gitlab-mcp
    docker run -d \
  -e HOST=0.0.0.0 \
  -e STREAMABLE_HTTP=true \
  -e REMOTE_AUTHORIZATION=true \
  -e GITLAB_API_URL="https://gitlab.com/api/v4" \
  -e GITLAB_PERMISSION_MODE=readonly \
  -e SESSION_TIMEOUT_SECONDS=3600 \
  -p 3333:3002 \
  zereight050/gitlab-mcp

  6. Zoekt inline search syntax for GitLab code search

    main

    When using GitLab instances with Zoekt (exact code search), you can use rich inline syntax within the search parameter. If using these filters, it is preferred over using the separate filename, path, or extension parameters.

    Supported Syntax Examples:

    • class foo: Exact match for a class named foo.
    • foo file:\.js$: Search for foo in files matching a specific pattern.
    • foo lang:ruby: Search for foo specifically in Ruby files.
    • sym:foo: Search for the symbol foo.
    • foo -bar: Negation (search for foo but not bar).
    • case:yes: Case-sensitive search.

  7. Choose the correct OAuth configuration variable

    main

    Selecting the wrong environment variable will prevent OAuth from working correctly:

    • Use GITLAB_OAUTH_REDIRECT_URI when running a local/stdio OAuth flow (GITLAB_USE_OAUTH=true). This variable is used by the local OAuth client initialization path.
    • Use GITLAB_OAUTH_CALLBACK_PROXY=true when running a remote/public MCP server (GITLAB_MCP_OAUTH=true) where clients send their own callback URLs. The server builds the GitLab callback from MCP_SERVER_URL only when proxy mode is enabled.

  8. How MCP OAuth Proxy works (for Claude.ai and remote clients)

    main

    When GITLAB_MCP_OAUTH=true is enabled, the server acts as an OAuth 2.0 proxy for GitLab. This is designed for remote MCP clients like Claude.ai that support the OAuth browser flow. It eliminates the need for manual Personal Access Token management.

    Workflow:

    1. The client discovers the OAuth endpoint at /.well-known/oauth-authorization-server.
    2. The client performs Dynamic Client Registration (POST /register).
    3. The client redirects the user to the GitLab login page using a pre-registered GitLab OAuth Application.
    4. After authentication, GitLab redirects to the client's callback URL.
    5. The client then includes an Authorization: Bearer <token> header in all subsequent MCP requests.

    Key Requirements:

    • You must have a pre-registered GitLab OAuth Application with api, read_api, or read_user scopes.
    • The GitLab Application's Redirect URI must be set to {MCP_SERVER_URL}/callback if using GITLAB_OAUTH_CALLBACK_PROXY=true.
    • This mode only works with STREAMABLE_HTTP=true and is incompatible with SSE.

    Server Setup Example:

    docker run -d \
  -e STREAMABLE_HTTP=true \
  -e GITLAB_MCP_OAUTH=true \
  -e GITLAB_OAUTH_APP_ID="your-gitlab-oauth-app-client-id" \
  -e GITLAB_API_URL="https://gitlab.example.com/api/v4" \
  -e MCP_SERVER_URL="https://your-mcp-server.example.com" \
  -p 3002:3002 \
  zereight050/gitlab-mcp

    Client Configuration (e.g., Claude.ai):

    {
  "mcpServers": {
    "GitLab": {
      "url": "https://your-mcp-server.example.com/mcp"
    }
  }
}
    {
  "mcpServers": {
    "GitLab": {
      "url": "https://your-mcp-server.example.com/mcp"
    }
  }
}

  9. Manage Group Wiki pages

    main

    The GitLab MCP provides tools to manage wiki pages at the Group level rather than the Project level.

    Available Tools:

    • list_group_wiki_pages: List pages in a group (Read-only).
    • get_group_wiki_page: Get details of a specific group page (Read-only).
    • create_group_wiki_page: Create a new group page (Writes).
    • update_group_wiki_page: Update an existing group page (Writes).
    • delete_group_wiki_page: Remove a group page (Writes).

  10. How the GitLab Connection Pool works

    main

    The server manages multiple GitLab instances using a GitLabClientPool. This architecture allows for efficient resource usage when interacting with various GitLab hosts.

    Key Behaviors:

    • Automatic Client Creation: A new client configuration (including proxy and SSL settings) is created when a previously unseen GitLab API URL is encountered.
    • Connection Reuse: Requests to the same API URL reuse the existing client configuration.
    • Automatic Cleanup: Idle connections are removed after the GITLAB_POOL_IDLE_TIMEOUT period.
    • LRU Eviction: If the pool reaches GITLAB_POOL_MAX_SIZE, the least recently used client is evicted to make room for new ones.

  11. Security best practices for GitLab tokens

    main

    When configuring GitLab access for the MCP server or testing environments, follow these security guidelines:

    • No Hardcoding: Never commit GitLab tokens directly in your source code.
    • Principle of Least Privilege: Grant tokens only the minimal required permissions (e.g., read_api, write_repository).
    • Rotation: Rotate your tokens regularly to minimize the impact of a potential leak.

  12. How session management and rotation work in stateless mode

    main

    Stateless mode uses a sealed Mcp-Session-Id (sid) to maintain authentication across requests.

    Session ID Rotation

    The Mcp-Session-Id rotates on every authenticated /mcp request. Each response carries a new sid with an embedded iat (issued at) timestamp. Clients must adopt the latest sid from every response to maintain the session.

    Session Lifetime (Inactivity Timeout)

    The OAUTH_STATELESS_SESSION_TTL_SECONDS variable acts as an inactivity timeout. Because the iat advances on every request, a continuously used session will persist indefinitely. A session is only rejected if no traffic is received for longer than the configured TTL.

    Error Handling and Recovery

    • 404 Session not found: Returned when a sid is expired (past the inactivity window), tampered with, or sealed with a different key. MCP SDK clients handle this by automatically starting a fresh initialize handshake.
    • 401 Authentication required: Returned only when a request lacks both a sid and any live authentication header (e.g., Authorization, Private-Token).
    • Recovery: If a client has live credentials (like an OAuth bearer token), it can recover from a 404 by re-sending the request with both the stale sid and the live header. Live authentication takes priority.