STARWARCLOUD STARWAR.AI
返回市场
GitLab-MCP

GitLab-MCP

作者：zereight760 星标更新：2025-11-24
安装使用来源：spider==github.com

项目介绍

技术文档摘要

GitLab MCP 服务器

Star History Chart

@zereight/mcp-gitlab

smithery badge

GitLab MCP（模型上下文协议）服务器。包含对原始 GitLab MCP 服务器的错误修复和改进。

<a href="https://glama.ai/mcp/servers/7jwbk4r6d7"><img width="380" height="200" src="https://gips2.baidu.com/it/u=2556439823,1539255757&fm=3081&app=3081&f=PNG?w=760&h=400" alt="gitlab mcp MCP 服务器" /></a>

使用方法

与 Claude App、Cline、Roo Code、Cursor、Kilo Code 一起使用

当与 Claude App 一起使用时，需要直接设置您的 API 密钥和 URL。

认证方法

该服务器支持两种认证方法：

  1. 个人访问令牌（传统方法）
  2. OAuth2（推荐用于更好的安全性）

使用 OAuth2 认证

OAuth2 提供了通过浏览器认证的安全认证流程。启用后，服务器会：

  1. 打开您的浏览器到 GitLab 的授权页面
  2. 等待您批准访问
  3. 安全地存储令牌以备将来使用
  4. 当令牌过期时自动刷新令牌

有关详细的 OAuth2 设置说明，请参阅 OAuth 设置指南。

快速设置 - 首先创建一个 GitLab OAuth 应用程序：

  1. 转到您的 GitLab 实例：设置 → 应用程序
  2. 创建一个新的应用程序：
    • 名称：GitLab MCP 服务器（或任何您喜欢的名称）
    • 重定向 URI：http://127.0.0.1:8888/callback
    • 范围：选择 api（提供完整的读写 API 访问权限）
  3. 复制 应用 ID（这是您的客户端 ID）

然后使用 OAuth 配置 MCP 服务器：

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@zereight/mcp-gitlab"],
      "env": {
        "GITLAB_USE_OAUTH": "true",
        "GITLAB_OAUTH_CLIENT_ID": "your_oauth_client_id",
        "GITLAB_OAUTH_REDIRECT_URI": "http://127.0.0.1:8888/callback",
        "GITLAB_API_URL": "your_gitlab_api_url",
        "GITLAB_PROJECT_ID": "your_project_id", // 可选：默认项目
        "GITLAB_ALLOWED_PROJECT_IDS": "", // 可选：允许项目的逗号分隔列表
        "GITLAB_READ_ONLY_MODE": "false",
        "USE_GITLAB_WIKI": "false", // 是否使用 wiki API？
        "USE_MILESTONE": "false", // 是否使用里程碑 API？
        "USE_PIPELINE": "false" // 是否使用流水线 API？
      }
    }
  }
}

使用个人访问令牌（传统方式）

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@zereight/mcp-gitlab"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "your_gitlab_token",
        "GITLAB_API_URL": "your_gitlab_api_url",
        "GITLAB_PROJECT_ID": "your_project_id", // 可选：默认项目
        "GITLAB_ALLOWED_PROJECT_IDS": "", // 可选：允许项目的逗号分隔列表
        "GITLAB_READ_ONLY_MODE": "false",
        "USE_GITLAB_WIKI": "false", // 是否使用 wiki API？
        "USE_MILESTONE": "false", // 是否使用里程碑 API？
        "USE_PIPELINE": "false" // 是否使用流水线 API？
      }
    }
  }
}

vscode .vscode/mcp.json

{
  "inputs": [
    {
      "type": "promptString",
      "id": "gitlab-token",
      "description": "Gitlab Token 以读取 API",
      "password": true
    }
  ],
  "servers": {
    "GitLab-MCP": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@zereight/mcp-gitlab"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "${input:gitlab-token}",
        "GITLAB_API_URL": "your-fancy-gitlab-url",
        "GITLAB_READ_ONLY_MODE": "true",
        ...
      }
    }
  }
}

Strands Agents SDK (MCP 工具)

env_vars = {
        "GITLAB_PERSONAL_ACCESS_TOKEN": gitlab_access_token,
        "GITLAB_API_URL": gitlab_api_url,
        "USE_GITLAB_WIKI": use_gitlab_wiki
        # ......其余可选参数
}

stdio_gitlab_mcp_client = MCPClient(
        lambda: stdio_client(
            StdioServerParameters(
                command="npx",
                args=["-y", "@zereight/mcp-gitlab"],
                env=env_vars,
            )
        )
    )

Docker

  • stdio mcp.json
{
  "mcpServers": {
    "gitlab": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITLAB_PERSONAL_ACCESS_TOKEN",
        "-e",
        "GITLAB_API_URL",
        "-e",
        "GITLAB_READ_ONLY_MODE",
        "-e",
        "USE_GITLAB_WIKI",
        "-e",
        "USE_MILESTONE",
        "-e",
        "USE_PIPELINE",
        "iwakitakuma/gitlab-mcp"
      ],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "your_gitlab_token",
        "GITLAB_API_URL": "https://gitlab.com/api/v4", // 可选，自托管 GitLab
        "GITLAB_READ_ONLY_MODE": "false",
        "USE_GITLAB_WIKI": "true",
        "USE_MILESTONE": "true",
        "USE_PIPELINE": "true"
      }
    }
  }
}
  • sse
docker run -i --rm \
  -e GITLAB_PERSONAL_ACCESS_TOKEN=your_gitlab_token \
  -e GITLAB_API_URL="https://gitlab.com/api/v4" \
  -e GITLAB_READ_ONLY_MODE=true \
  -e USE_GITLAB_WIKI=true \
  -e USE_MILESTONE=true \
  -e USE_PIPELINE=true \
  -e SSE=true \
  -p 3333:3002 \
  iwakitakuma/gitlab-mcp

{
  "mcpServers": {
    "gitlab": {
      "type": "sse",
      "url": "http://localhost:3333/sse"
    }
  }
}
  • streamable-http
docker run -i --rm \
  -e GITLAB_PERSONAL_ACCESS_TOKEN=your_gitlab_token \
  -e GITLAB_API_URL="https://gitlab.com/api/v4" \
  -e GITLAB_READ_ONLY_MODE=true \
  -e USE_GITLAB_WIKI=true \
  -e USE_MILESTONE=true \
  -e USE_PIPELINE=true \
  -e STREAMABLE_HTTP=true \
  -p 3333:3002 \
  iwakitakuma/gitlab-mcp

{
  "mcpServers": {
    "gitlab": {
      "type": "streamable-http",
      "url": "http://localhost:3333/mcp"
    }
  }
}

环境变量

认证配置

  • GITLAB_PERSONAL_ACCESS_TOKEN：您的 GitLab 个人访问令牌。标准模式下必需；当 REMOTE_AUTHORIZATION=true 或使用 OAuth 时未使用。
  • GITLAB_USE_OAUTH：设置为 true 启用 OAuth2 认证而不是个人访问令牌。
  • GITLAB_OAUTH_CLIENT_ID：来自您的 GitLab OAuth 应用程序的客户端 ID。使用 OAuth 时必需。
  • GITLAB_OAUTH_REDIRECT_URI：OAuth 回调 URL。默认值：http://127.0.0.1:8888/callback
  • GITLAB_OAUTH_TOKEN_PATH：自定义 OAuth 令牌存储路径。默认值：~/.gitlab-mcp-token.json
  • REMOTE_AUTHORIZATION：设置为 'true' 启用远程会话认证通过 HTTP 头。在这种模式下：
    • 服务器接受来自 HTTP 头（Authorization: Bearer <token> 或 Private-Token: <token>）的 GitLab PAT 令牌，按会话基础
    • 不需要且忽略 GITLAB_PERSONAL_ACCESS_TOKEN 环境变量
    • 仅适用于 流式 HTTP 传输（STREAMABLE_HTTP=true），因为会话管理已由传输层处理
    • 禁用 SSE 传输 - 尝试在远程认证中使用 SSE 将导致服务器退出并报错
    • 每个客户端会话可以使用不同的令牌，实现多用户支持和安全会话隔离
    • 令牌按会话存储，并在会话关闭或超时时自动清理
  • SESSION_TIMEOUT_SECONDS：会话认证令牌超时时间（秒）。默认值：3600（1小时）。有效范围：1-86400 秒（建议：60+）。在此期间内无活动后，认证令牌将被移除但传输会话仍保持活跃。客户端必须在下次请求时再次提供认证头。仅当 REMOTE_AUTHORIZATION=true 时适用。

通用配置

  • GITLAB_API_URL：您的 GitLab API URL。（默认：https://gitlab.com/api/v4）
  • GITLAB_PROJECT_ID：默认项目 ID。如果设置，则在进行 API 请求时覆盖此值。
  • GITLAB_ALLOWED_PROJECT_IDS：可选的允许项目 ID 列表，逗号分隔。当设置为单个值时，作为默认项目（类似于旧的“锁定”模式）。当设置为多个值时，限制访问这些项目。示例：
    • 单个值 123：MCP 服务器只能访问项目 123 并将其作为默认项目
    • 多个值 123,456,789：MCP 服务器可以访问项目 123、456 和 789，但在请求中需要明确指定项目 ID
  • GITLAB_READ_ONLY_MODE：设置为 'true' 时，限制服务器仅暴露只读操作。对于增强安全或不需要写入访问的情况有用。也适用于与 Cursor 一起使用及其 40 工具限制。
  • GITLAB_DENIED_TOOLS_REGEX：当设置为正则表达式时，排除匹配的工具。
  • USE_GITLAB_WIKI：设置为 'true' 时，启用与 wiki 相关的工具（list_wiki_pages, get_wiki_page, create_wiki_page, update_wiki_page, delete_wiki_page）。默认情况下，wiki 功能是禁用的。
  • USE_MILESTONE：设置为 'true' 时，启用与里程碑相关的工具（list_milestones, get_milestone, create_milestone, edit_milestone, delete_milestone, get_milestone_issue, get_milestone_merge_requests, promote_milestone, get_milestone_burndown_events）。默认情况下，里程碑功能是禁用的。
  • USE_PIPELINE：设置为 'true' 时，启用与流水线相关的工具（list_pipelines, get_pipeline, list_pipeline_jobs, list_pipeline_trigger_jobs, get_pipeline_job, get_pipeline_job_output, create_pipeline, retry_pipeline, cancel_pipeline, play_pipeline_job, retry_pipeline_job, cancel_pipeline_job）。默认情况下，流水线功能是禁用的。
  • GITLAB_AUTH_COOKIE_PATH：指向 GitLab 实例所需的认证 cookie 文件路径。当提供时，cookie 将包含在所有 GitLab API 请求中。
  • SSE：设置为 'true' 时，启用 Server-Sent Events 传输。
  • STREAMABLE_HTTP：设置为 'true' 时，启用流式 HTTP 传输。如果同时设置了 SSE 和 STREAMABLE_HTTP 为 'true'，服务器将优先使用流式 HTTP 传输。
  • GITLAB_COMMIT_FILES_PER_PAGE：GitLab 返回的提交差异每页文件数量。此值应与服务器端 GitLab 设置相匹配。如果您的 GitLab 实例使用自定义每页值，请调整此值。

性能及安全配置

  • MAX_SESSIONS：允许的最大并发会话数。默认值：1000。有效范围：1-10000。达到限制时，新连接将以 HTTP 503 拒绝。
  • MAX_REQUESTS_PER_MINUTE：每个会话的每分钟速率限制。默认值：60。有效范围：1-1000。超过限制的请求返回 HTTP 429。
  • PORT：服务器端口。默认值：3002。有效范围：1-65535。

监控端点

当使用流式 HTTP 传输时，以下端点可用：

  • /health：健康检查端点，返回服务器状态、活动会话计数和运行时间。
  • /metrics：详细指标包括：
    • 活动和总会话计数
    • 认证指标（失败次数、过期次数）
    • 速率限制统计
    • 资源使用情况（内存、运行时间）
    • 配置概要

远程认证设置（多用户支持）

当使用 REMOTE_AUTHORIZATION=true 时，MCP 服务器可以支持多个用户，每个用户的 GitLab 令牌通过 HTTP 头传递。这适用于：

  • 共享 MCP 服务器实例，每个用户需要自己的 GitLab 访问
  • 可注入用户特定令牌到 MCP 请求中的 IDE 集成

设置示例：

# 启动具有远程认证的服务器
docker run -d \
  -e STREAMABLE_HTTP=true \
  -e REMOTE_AUTHORIZATION=true \
  -e GITLAB_API_URL="https://gitlab.com/api/v4" \
  -e GITLAB_READ_ONLY_MODE=true \
  -e SESSION_TIMEOUT_SECONDS=3600 \
  -p 3333:3002 \
  iwakitakuma/gitlab-mcp

客户端配置：

您的 IDE 或 MCP 客户端必须在每次请求中发送以下之一的头部：

Authorization: Bearer glpat-xxxxxxxxxxxxxxxxxxxx

或

Private-Token: glpat-xxxxxxxxxxxxxxxxxxxx

令牌按会话存储（通过 mcp-session-id 头标识）并在同一会话中的后续请求中重复使用。

使用 Cursor 的远程认证客户端配置示例

{
  "mcpServers": {
    "GitLab": {
      "url": "http(s)://<your_mcp_gitlab_server>/mcp",
      "headers": {
        "Authorization": "Bearer glpat-..."
      }
    }
  }
}

重要提示：

  • 远程认证仅适用于流式 HTTP 传输
  • 每个会话都是隔离的 - 一个会话中的令牌无法访问另一个会话的数据
  • 令牌在会话关闭时自动清理
  • 会话超时：认证令牌在 SESSION_TIMEOUT_SECONDS（默认 1 小时）的不活动后过期。超时后，客户端必须再次发送认证头。传输会话仍然活跃。
  • 每次请求都会重置该会话的超时计时器
  • 速率限制：每个会话每分钟限制为 MAX_REQUESTS_PER_MINUTE 次请求（默认 60）
  • 容量限制：服务器接受最多 MAX_SESSIONS 并发会话（默认 1000）

工具 🛠️

<details> <summary>点击展开</summary> <!-- TOOLS-START -->
  1. merge_merge_request - 在 GitLab 项目中合并合并请求
  2. create_or_update_file - 在 GitLab 项目中创建或更新单个文件
  3. search_repositories - 搜索 GitLab 项目
  4. create_repository - 创建新的 GitLab 项目
  5. get_file_contents - 获取 GitLab 项目中的文件或目录内容
  6. push_files - 将多个文件推送到 GitLab 项目中的单个提交
  7. create_issue - 在 GitLab 项目中创建新的问题
  8. create_merge_request - 在 GitLab 项目中创建新的合并请求
  9. fork_repository - 将 GitLab 项目 fork 到您的账户或指定命名空间
  10. create_branch - 在 GitLab 项目中创建新的分支
  11. get_merge_request - 获取合并请求的详细信息（必须提供 mergeRequestIid 或 branchName）
  12. get_merge_request_diffs - 获取合并请求的更改/差异（必须提供 mergeRequestIid 或 branchName）
  13. list_merge_request_diffs - 列出带有分页支持的合并请求差异（必须提供 mergeRequestIid 或 branchName）
  14. get_branch_diffs - 获取两个分支或提交之间的更改/差异
  15. update_merge_request - 更新合并请求（必须提供 mergeRequestIid 或 branchName）
  16. create_note - 在问题或合并请求上创建新的注释
  17. create_merge_request_thread - 在合并请求上