GitLab MCP服务器

![Star History Chart](https://www.star-history.com/#zereight/gitlab-mcp&Date)

@zereight/mcp gitlab

](https://smithery.ai/server/@zereight/gitlab-mcp)

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

用法

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

使用Claude应用程序时，您需要直接设置API密钥和URL。

新巴拿马型船舶

{
  "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", // Optional: default project
        "GITLAB_ALLOWED_PROJECT_IDS": "", // Optional: comma-separated list of allowed project IDs
        "GITLAB_READ_ONLY_MODE": "false",
        "USE_GITLAB_WIKI": "false", // use wiki api?
        "USE_MILESTONE": "false", // use milestone api?
        "USE_PIPELINE": "false" // use pipeline api?
      }
    }
  }
}

vscode.vcode/mcp.json

{
  "inputs": [
    {
      "type": "promptString",
      "id": "gitlab-token",
      "description": "Gitlab Token to read 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",
        ...
      }
    }
  }
}

码头工人

斯泰迪奥·麦克普森

{
  "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", // Optional, for self-hosted GitLab
        "GITLAB_READ_ONLY_MODE": "false",
        "USE_GITLAB_WIKI": "true",
        "USE_MILESTONE": "true",
        "USE_PIPELINE": "true"
      }
    }
  }
}

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"
    }
  }
}

可流式传输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.
REMOTE_AUTHORIZATION：设置为“true”时，通过HTTP标头启用远程每会话授权。在此模式下：

- 服务器接受来自HTTP标头的GitLab PAT令牌(Authorization: Bearer 或 Private-Token: )按每节课计算 - 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”时，限制服务器仅公开只读操作。对于增强安全性或不需要写访问时很有用。对于与游标一起使用也很有用，它有40个工具限制。
GITLAB_DENIED_TOOLS_REGEX：当设置为正则表达式时，它将排除匹配工具。
USE_GITLAB_WIKI：设置为“true”时，启用wiki相关工具（list_wiki_pages、get_wiki_page、create_wiki_page、update_wiki_ppage、delete_wiki_plage）。默认情况下，wiki功能处于禁用状态。
USE_MILESTONE：当设置为“true”时，启用与里程碑相关的工具（list_milestones、get_milestone、create_milestone、edit_milestone、delete_milestone-issue、get_milstone_merge_requests、promote_milestoney、get_miletone_burndown_events）。默认情况下，里程碑功能处于禁用状态。
USE_PIPELINE：当设置为“true”时，启用与管道相关的工具（list_pipelines、get_pipeline、list_pipeline_jobs、list_ppipeline_trigger_jobs，get_pipeline_job、get_ipeline_job_output、create_pipeline、retry_pipeline、cancel_pipeline，play_pipeline\_ job、retry_ipeline_jo、cancel_pipeline_jb）。默认情况下，管道功能处于禁用状态。
GITLAB_AUTH_COOKIE_PATH：需要基于cookie的身份验证的GitLab实例的身份验证cookie文件的路径。一旦提供，cookie将包含在所有GitLab API请求中。
SSE：设置为“true”时，启用服务器发送事件传输。
STREAMABLE_HTTP：设置为“true”时，启用流式HTTP传输。如果两者 上海证券交易所 和 STREAMABLE_HTTP 如果设置为“true”，服务器将优先考虑Streamable HTTP而不是SSE传输。
GITLAB_COMMIT_FILES_PER_PAGEGitLab为提交差异返回的每页文件数。此值应与服务器端的GitLab设置匹配。如果您的GitLab实例对提交差异使用自定义的每页值，请调整此设置。

性能和安全配置

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

监控端点

使用Streamable HTTP传输时，以下端点可用：

/health：健康检查端点返回服务器状态、活动会话计数和正常运行时间。
/metrics：详细指标包括：

- 活动会话数和总会话数 - 身份验证指标（失败、过期） - 速率限制统计 - 资源使用情况（内存、正常运行时间） - 配置摘要

远程授权设置（多用户支持）

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

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

设置示例：

# Start server with remote authorization
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 header），并在同一会话中重复用于后续请求。

带游标的远程授权客户端配置示例

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

重要提示：

远程授权 仅适用于流式HTTP传输
每个会话都是隔离的-来自一个会话的令牌无法访问另一个会话中的数据

会话结束时，令牌会自动清理

会话超时： 身份验证令牌在以下时间过期 SESSION_TIMEOUT_SECONDS （默认1小时）不活动。超时后，客户端必须再次发送身份验证标头。传输会话仍处于活动状态。
每个请求都会重置该会话的超时计时器
速率限制： 每次会议仅限于 MAX_REQUESTS_PER_MINUTE 每分钟请求数（默认值60）
容量限制： 服务器最多可接受 MAX_SESSIONS 并发会话（默认值1000）

工具🛠️

Click to expand

merge_merge_request -在GitLab项目中合并合并请求
create_or_update_file -在GitLab项目中创建或更新单个文件
search_repositories -搜索GitLab项目
create_repository -创建一个新的GitLab项目
get_file_contents -从GitLab项目中获取文件或目录的内容
push_files -在一次提交中将多个文件推送到GitLab项目中
create_issue -在GitLab项目中创建新问题
create_merge_request -在GitLab项目中创建新的合并请求
fork_repository -将GitLab项目分叉到您的帐户或指定的命名空间
create_branch -在GitLab项目中创建一个新分支
get_merge_request -获取合并请求的详细信息（必须提供mergeRequestIid或branchName）
get_merge_request_diffs -获取合并请求的更改/差异（必须提供mergeRequestIid或branchName）
list_merge_request_diffs -列出具有分页支持的合并请求差异（必须提供mergeRequestIid或branchName）
get_branch_diffs -获取GitLab项目中两个分支或提交之间的更改/差异
update_merge_request -更新合并请求（必须提供mergeRequestIid或branchName）
create_note -为问题或合并请求创建新注释（注释）
create_merge_request_thread -在合并请求上创建新线程
mr_discussions -列出合并请求的讨论项
update_merge_request_note -修改现有的合并请求线程注释
create_merge_request_note -向现有合并请求线程添加新注释
get_draft_note -从合并请求中获取单个草稿笔记
list_draft_notes -列出合并请求的草稿注释
create_draft_note -为合并请求创建草稿注释
update_draft_note -更新现有的说明草稿
delete_draft_note -删除草稿注释
publish_draft_note -发布单个草稿注释
bulk_publish_draft_notes -发布合并请求的所有草稿注释
update_issue_note -修改现有问题线索注释
create_issue_note -向现有问题线程添加新注释
list_issues -列出问题（默认值：仅由当前用户创建；对所有可访问的问题使用范围=“全部”）
my_issues -列出分配给已验证用户的问题（默认为未解决问题）
get_issue -获取GitLab项目中特定问题的详细信息
update_issue -更新GitLab项目中的问题
delete_issue -从GitLab项目中删除问题
list_issue_links -列出特定问题的所有问题链接
list_issue_discussions -列出GitLab项目中某个问题的讨论
get_issue_link -获取特定问题链接
create_issue_link -在两个问题之间创建问题链接
delete_issue_link -删除问题链接
list_namespaces -列出当前用户可用的所有命名空间
get_namespace -通过ID或路径获取命名空间的详细信息
verify_namespace -验证命名空间路径是否存在
get_project -获取特定项目的详细信息
list_projects -列出当前用户可访问的项目
list_project_members -列出GitLab项目的成员
list_labels -列出项目的标签
get_label -从项目中获取单个标签
create_label -在项目中创建新标签
update_label -更新项目中的现有标签
delete_label -从项目中删除标签
list_group_projects -列出GitLab组中具有筛选选项的项目
list_wiki_pages -列出GitLab项目中的wiki页面
get_wiki_page -获取特定wiki页面的详细信息
create_wiki_page -在GitLab项目中创建一个新的wiki页面
update_wiki_page -更新GitLab项目中的现有wiki页面
delete_wiki_page -从GitLab项目中删除wiki页面
get_repository_tree -获取GitLab项目的存储库树（列出文件和目录）
list_pipelines -列出GitLab项目中带有过滤选项的管道
get_pipeline -获取GitLab项目中特定管道的详细信息
list_pipeline_jobs -列出特定管道中的所有作业
list_pipeline_trigger_jobs -列出特定管道中触发下游管道的所有触发作业（桥）
get_pipeline_job -获取GitLab管道作业号的详细信息
get_pipeline_job_output -使用可选分页获取GitLab管道作业的输出/跟踪，以限制上下文窗口的使用
create_pipeline -为分支或标记创建新管道
retry_pipeline -重试失败或取消的管道
cancel_pipeline -取消正在运行的管道
play_pipeline_job -运行手动管道作业
retry_pipeline_job -重试失败或取消的管道作业
cancel_pipeline_job -取消正在运行的管道作业
list_merge_requests -在GitLab项目中列出带有过滤选项的合并请求
list_milestones -列出GitLab项目中具有过滤选项的里程碑
get_milestone -获取特定里程碑的详细信息
create_milestone -在GitLab项目中创建新的里程碑
edit_milestone -编辑GitLab项目中的现有里程碑
delete_milestone -从GitLab项目中删除里程碑
get_milestone_issue -获取与特定里程碑相关的问题
get_milestone_merge_requests -获取与特定里程碑关联的合并请求
promote_milestone -将里程碑推进到下一阶段
get_milestone_burndown_events -获取特定里程碑的烧毁事件
get_users -按用户名获取GitLab用户详细信息
list_commits -列出带有筛选选项的存储库提交
get_commit -获取特定提交的详细信息
get_commit_diff -获取特定提交的更改/差异
list_group_iterations -列出具有过滤选项的组迭代
upload_markdown -将文件上传到GitLab项目以用于markdown内容
download_attachment -通过secret和filename从GitLab项目下载上传的文件
list_events -列出当前已验证用户的所有事件
get_project_events -列出指定项目的所有可见事件
list_releases -列出项目的所有版本
get_release -按标签名称获取发布
create_release -在GitLab项目中创建新版本
update_release -更新GitLab项目中的现有版本
delete_release -从GitLab项目中删除一个版本（不删除关联的标签）
create_release_evidence -为现有版本创建发布证据（仅限GitLab Premium/Ultimate）
download_release_asset -通过直接资产路径下载发布资产文件

测试🧪

该项目包括全面的测试覆盖，包括远程授权：

# Run all tests (API validation + remote auth)
npm test

# Run only remote authorization tests
npm run test:remote-auth

# Run all tests including readonly MCP tests
npm run test:all

# Run only API validation
npm run test:integration

所有远程授权测试都使用模拟的GitLab服务器，不需要实际的GitLab凭据。

Adapters Gitlab MCP Server

快速接入

详细介绍