From ad02259800a6c9745a61b0fc8ce8a98c2a8c5c97 Mon Sep 17 00:00:00 2001 From: zereight Date: Mon, 12 Oct 2026 10:17:47 +0900 Subject: [PATCH 1/2] docs(readme): add GitLab official MCP server comparison and quick setup table --- README.ko.md | 36 ++++++++++++++++++----- README.md | 36 ++++++++++++++++++----- README.pt-BR.md | 36 ++++++++++++++++++----- README.zh-CN.md | 36 ++++++++++++++++++----- docs/comparison/community-gitlab-mcp-a.md | 2 +- docs/comparison/index.md | 1 + 6 files changed, 114 insertions(+), 33 deletions(-) diff --git a/README.ko.md b/README.ko.md index 10f94b783..9862fbdd0 100644 --- a/README.ko.md +++ b/README.ko.md @@ -7,6 +7,18 @@ 📖 **[문서 →](https://zereight.github.io/gitlab-mcp/)** 설정 가이드, 환경 변수, 전체 도구 레퍼런스는 호스팅된 문서 사이트에서 확인할 수 있습니다. +`@zereight/mcp-gitlab`의 권장 로컬 PAT 설치입니다. 명령 인자는 [Claude Code](./docs/clients/claude-code.md)와 [Codex](./docs/clients/codex.md) 가이드와 같습니다. + +`zereight-mcp-gitlab` 바이너리를 먼저 설치하세요. `npm install -g @zereight/mcp-gitlab`, 또는 Homebrew `brew tap zereight/gitlab-mcp https://github.com/zereight/gitlab-mcp` 다음 `brew install zereight/gitlab-mcp/zereight-mcp-gitlab`. + +| 클라이언트 | 설치 | +| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Claude Code | `claude mcp add gitlab --transport stdio --scope local --env GITLAB_PERSONAL_ACCESS_TOKEN=glpat-your-token --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab` | +| Codex | `codex mcp add gitlab --env GITLAB_PERSONAL_ACCESS_TOKEN=glpat-your-token --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab` | +| Cursor | [Cursor 설정 가이드](./docs/clients/cursor.md) | +| VS Code | [VS Code 설정 가이드](./docs/clients/vscode.md) | +| JSON 클라이언트 | [JSON 기반 MCP 클라이언트 설정 가이드](./docs/clients/json-clients.md) | + [![Star History Chart](./assets/star-history.png)](https://www.star-history.com/?repos=zereight%2Fgitlab-mcp&type=date&legend=top-left) ## @zereight/mcp-gitlab @@ -28,15 +40,23 @@ PAT, OAuth, 읽기 전용 모드, 동적 API URL, 원격 인증을 지원하며 ### 비교 요약 -| | @zereight/mcp-gitlab | GitLab MCP A (커뮤니티 CQRS형) | -|---|----------------------|--------------------------------| -| **적합한 경우** | AI 에이전트 워크플로우 | 엔터프라이즈 멀티 인스턴스 / 그룹형 도구 | -| **도구 모델** | 274개 도구: toolset 272개 + `execute_graphql` + `discover_tools` | ~50–60개 `browse_*` / `manage_*` 그룹 도구 | -| **MR 리뷰** | 2단계 배치 diff | 서버마다 다름 | -| **Node.js** | >=18.17 | 보통 >=24 | -| **라이선스** | MIT | 서버마다 다름 | +| | @zereight/mcp-gitlab | GitLab MCP A (커뮤니티 CQRS형) | GitLab 공식 MCP 서버 | +| --------------- | ---------------------------------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | +| **적합한 경우** | AI 에이전트 워크플로우 | 엔터프라이즈 멀티 인스턴스 / 그룹형 도구 | GitLab에 내장, 별도 설치 없음 | +| **도구 모델** | 274개 도구: toolset 272개 + `execute_graphql` + `discover_tools` | ~50–60개 `browse_*` / `manage_*` 그룹 도구 | HTTP 헤더로 고르는 toolset | +| **MR 리뷰** | 2단계 배치 diff | 서버마다 다름 | `get_merge_request`에 diffs | +| **Node.js** | >=18.17 | 보통 >=24 | stdio는 `mcp-remote`, Node.js 20+ | +| **라이선스** | MIT | 서버마다 다름 | GitLab의 일부 | + +[GitLab MCP A 전체 비교 →](./docs/comparison/community-gitlab-mcp-a.md) + +GitLab은 [공식 MCP 서버](https://docs.gitlab.com/user/model_context_protocol/mcp_server/)도 제공합니다. -[전체 비교 →](./docs/comparison/community-gitlab-mcp-a.md) +- Free, Premium, Ultimate. GitLab 19.2에서 Premium에서 Free로 옮겨졌고, GitLab 19.5에서 GA입니다. +- GitLab.com에서는 최상위 그룹 Owner가 MCP 서버 접근을 허용합니다. GitLab Self-Managed와 GitLab Dedicated는 인스턴스 설정입니다. 기본값 규칙은 공식 페이지에 있습니다. +- 원격 클라이언트는 HTTP `https:///api/v4/mcp`와 OAuth 2.0 동적 클라이언트 등록을 사용합니다. +- stdio는 `mcp-remote`를 거치며 Node.js 20 이상이 필요합니다. +- Toolset은 `X-Gitlab-Enabled-Mcp-Server-Toolsets` 헤더를 사용합니다. 선택 헤더 `X-Gitlab-Mcp-Server-Tool-Name-Prefix`는 도구 이름 접두사의 앞 32자만 유지합니다. 빠른 시작: 아래에서 Personal Access Token 또는 OAuth2 설정 중 하나를 선택하고 `@zereight/mcp-gitlab`을 설치한 뒤 MCP 클라이언트 설정에서 `zereight-mcp-gitlab`을 사용하세요. diff --git a/README.md b/README.md index db48a6377..b389e3f17 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,18 @@ 📖 **[Documentation →](https://zereight.github.io/gitlab-mcp/)** Setup guides, environment variables, and the full tool reference live on the hosted docs site. +Install `@zereight/mcp-gitlab` with the recommended local personal-access-token setup. These commands use the same arguments as the [Claude Code](./docs/clients/claude-code.md) and [Codex](./docs/clients/codex.md) guides. + +Install the `zereight-mcp-gitlab` binary first with `npm install -g @zereight/mcp-gitlab`, or Homebrew `brew tap zereight/gitlab-mcp https://github.com/zereight/gitlab-mcp` and `brew install zereight/gitlab-mcp/zereight-mcp-gitlab`. + +| Client | Install | +| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Claude Code | `claude mcp add gitlab --transport stdio --scope local --env GITLAB_PERSONAL_ACCESS_TOKEN=glpat-your-token --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab` | +| Codex | `codex mcp add gitlab --env GITLAB_PERSONAL_ACCESS_TOKEN=glpat-your-token --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab` | +| Cursor | [Cursor setup guide](./docs/clients/cursor.md) | +| VS Code | [VS Code setup guide](./docs/clients/vscode.md) | +| JSON clients | [JSON-based MCP clients setup guide](./docs/clients/json-clients.md) | + [![Star History Chart](./assets/star-history.png)](https://www.star-history.com/?repos=zereight%2Fgitlab-mcp&type=date&legend=top-left) ## @zereight/mcp-gitlab @@ -33,15 +45,23 @@ Supports PAT, OAuth, read-only mode, dynamic API URLs, and remote authorization ### How we compare -| | @zereight/mcp-gitlab | GitLab MCP A (community CQRS-style) | -|---|----------------------|-------------------------------------| -| **Best for** | AI agent workflows | Enterprise multi-instance / grouped tools | -| **Tool model** | 274 tools: 272 in toolsets + `execute_graphql` + `discover_tools` | ~50–60 grouped `browse_*` / `manage_*` tools | -| **MR review** | 2-step batched diff | Varies | -| **Node.js** | >=18.17 | Often >=24 | -| **License** | MIT | Varies | +| | @zereight/mcp-gitlab | GitLab MCP A (community CQRS-style) | GitLab official MCP server | +| -------------- | ----------------------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| **Best for** | AI agent workflows | Enterprise multi-instance / grouped tools | Built into GitLab, no separate install | +| **Tool model** | 274 tools: 272 in toolsets + `execute_graphql` + `discover_tools` | ~50–60 grouped `browse_*` / `manage_*` tools | Toolsets chosen with an HTTP header | +| **MR review** | 2-step batched diff | Varies | `get_merge_request` with diffs | +| **Node.js** | >=18.17 | Often >=24 | Node.js 20+ for stdio via `mcp-remote` | +| **License** | MIT | Varies | Part of GitLab | + +[Full comparison with GitLab MCP A →](./docs/comparison/community-gitlab-mcp-a.md) + +GitLab also ships an [official MCP server](https://docs.gitlab.com/user/model_context_protocol/mcp_server/). -[Full comparison →](./docs/comparison/community-gitlab-mcp-a.md) +- Free, Premium, and Ultimate. Moved from Premium to Free in GitLab 19.2. Generally available in GitLab 19.5. +- On GitLab.com, a top-level group Owner allows access to the MCP server. On GitLab Self-Managed and GitLab Dedicated, an administrator controls the instance setting. Default rules are on the official page. +- Remote clients use HTTP `https:///api/v4/mcp` with OAuth 2.0 dynamic client registration. +- stdio goes through `mcp-remote` and needs Node.js 20 or later. +- Toolsets use the `X-Gitlab-Enabled-Mcp-Server-Toolsets` header. An optional `X-Gitlab-Mcp-Server-Tool-Name-Prefix` header keeps the first 32 characters of a tool-name prefix. Quick start: choose either Personal Access Token or OAuth2 setup below, install `@zereight/mcp-gitlab`, and use `zereight-mcp-gitlab` in your MCP client configuration. diff --git a/README.pt-BR.md b/README.pt-BR.md index 33db866fd..a57632baf 100644 --- a/README.pt-BR.md +++ b/README.pt-BR.md @@ -7,6 +7,18 @@ 📖 **[Documentação →](https://zereight.github.io/gitlab-mcp/)** Guias de configuração, variáveis de ambiente e a referência completa de ferramentas estão disponíveis no site de documentação. +Instalação local recomendada com PAT para `@zereight/mcp-gitlab`. Os argumentos são os mesmos dos guias de [Claude Code](./docs/clients/claude-code.md) e [Codex](./docs/clients/codex.md). + +Instale o binário `zereight-mcp-gitlab` antes. `npm install -g @zereight/mcp-gitlab`, ou Homebrew `brew tap zereight/gitlab-mcp https://github.com/zereight/gitlab-mcp` e `brew install zereight/gitlab-mcp/zereight-mcp-gitlab`. + +| Cliente | Instalação | +| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Claude Code | `claude mcp add gitlab --transport stdio --scope local --env GITLAB_PERSONAL_ACCESS_TOKEN=glpat-your-token --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab` | +| Codex | `codex mcp add gitlab --env GITLAB_PERSONAL_ACCESS_TOKEN=glpat-your-token --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab` | +| Cursor | [Guia de configuração do Cursor](./docs/clients/cursor.md) | +| VS Code | [Guia de configuração do VS Code](./docs/clients/vscode.md) | +| Clientes JSON | [Guia para clientes MCP baseados em JSON](./docs/clients/json-clients.md) | + [![Star History Chart](./assets/star-history.png)](https://www.star-history.com/?repos=zereight%2Fgitlab-mcp&type=date&legend=top-left) ## @zereight/mcp-gitlab @@ -28,15 +40,23 @@ Suporta PAT, OAuth, modo somente leitura, URLs de API dinâmicas e autorização ### Comparação -| | @zereight/mcp-gitlab | GitLab MCP A (comunidade, estilo CQRS) | -| ------------------------- | ---------------------------------------------- | --------------------------------------------------------- | -| **Mais indicado para** | Workflows de agentes de IA | Múltiplas instâncias corporativas / ferramentas agrupadas | -| **Modelo de ferramentas** | 274 ferramentas: 272 em toolsets + `execute_graphql` + `discover_tools` | ~50–60 ferramentas agrupadas `browse_*` / `manage_*` | -| **Revisão de MR** | Diff em lote em 2 etapas | Varia | -| **Node.js** | >=18.17 | Frequentemente >=24 | -| **Licença** | MIT | Varia | +| | @zereight/mcp-gitlab | GitLab MCP A (comunidade, estilo CQRS) | Servidor MCP oficial do GitLab | +| ------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Mais indicado para** | Workflows de agentes de IA | Múltiplas instâncias corporativas / ferramentas agrupadas | Integrado ao GitLab, sem instalação separada | +| **Modelo de ferramentas** | 274 ferramentas: 272 em toolsets + `execute_graphql` + `discover_tools` | ~50–60 ferramentas agrupadas `browse_*` / `manage_*` | Toolsets escolhidos por cabeçalho HTTP | +| **Revisão de MR** | Diff em lote em 2 etapas | Varia | `get_merge_request` com diffs | +| **Node.js** | >=18.17 | Frequentemente >=24 | Node.js 20+ para stdio via `mcp-remote` | +| **Licença** | MIT | Varia | Parte do GitLab | + +[Comparação completa com o GitLab MCP A →](./docs/comparison/community-gitlab-mcp-a.md) + +O GitLab também inclui um [servidor MCP oficial](https://docs.gitlab.com/user/model_context_protocol/mcp_server/). -[Comparação completa →](./docs/comparison/community-gitlab-mcp-a.md) +- Free, Premium e Ultimate. Passou de Premium para Free no GitLab 19.2. Disponibilidade geral no GitLab 19.5. +- No GitLab.com, o Owner do grupo de nível superior permite o acesso ao servidor MCP. No GitLab Self-Managed e no GitLab Dedicated, um administrador controla a configuração da instância. As regras padrão estão na página oficial. +- Clientes remotos usam HTTP `https:///api/v4/mcp` com OAuth 2.0 dynamic client registration. +- O stdio passa por `mcp-remote` e exige Node.js 20 ou posterior. +- Os toolsets usam o cabeçalho `X-Gitlab-Enabled-Mcp-Server-Toolsets`. O cabeçalho opcional `X-Gitlab-Mcp-Server-Tool-Name-Prefix` mantém os primeiros 32 caracteres de um prefixo de nome de ferramenta. Início rápido: escolha abaixo uma configuração com Personal Access Token ou OAuth2, instale `@zereight/mcp-gitlab` e use `zereight-mcp-gitlab` na configuração do seu cliente MCP. diff --git a/README.zh-CN.md b/README.zh-CN.md index d812b3431..61c94f323 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -7,6 +7,18 @@ 📖 **[文档 →](https://zereight.github.io/gitlab-mcp/)** 设置指南、环境变量和完整工具参考请查看托管文档站点。 +下面是 `@zereight/mcp-gitlab` 的推荐本地 PAT 安装。命令参数与 [Claude Code](./docs/clients/claude-code.md) 和 [Codex](./docs/clients/codex.md) 指南相同。 + +先安装 `zereight-mcp-gitlab` 二进制。`npm install -g @zereight/mcp-gitlab`，或 Homebrew `brew tap zereight/gitlab-mcp https://github.com/zereight/gitlab-mcp` 然后 `brew install zereight/gitlab-mcp/zereight-mcp-gitlab`。 + +| 客户端 | 安装 | +| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Claude Code | `claude mcp add gitlab --transport stdio --scope local --env GITLAB_PERSONAL_ACCESS_TOKEN=glpat-your-token --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab` | +| Codex | `codex mcp add gitlab --env GITLAB_PERSONAL_ACCESS_TOKEN=glpat-your-token --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab` | +| Cursor | [Cursor 设置指南](./docs/clients/cursor.md) | +| VS Code | [VS Code 设置指南](./docs/clients/vscode.md) | +| JSON 客户端 | [基于 JSON 的 MCP 客户端设置指南](./docs/clients/json-clients.md) | + [![Star History Chart](./assets/star-history.png)](https://www.star-history.com/?repos=zereight%2Fgitlab-mcp&type=date&legend=top-left) ## @zereight/mcp-gitlab @@ -28,15 +40,23 @@ ### 对比摘要 -| | @zereight/mcp-gitlab | GitLab MCP A（社区 CQRS 型） | -|---|----------------------|------------------------------| -| **更适合** | AI 代理工作流 | 企业多实例 / 分组工具 | -| **工具模型** | 274 个工具：toolset 中 272 个 + `execute_graphql` + `discover_tools` | ~50–60 个 `browse_*` / `manage_*` 分组工具 | -| **MR 审查** | 两步批量 diff | 因服务器而异 | -| **Node.js** | >=18.17 | 通常 >=24 | -| **许可证** | MIT | 因服务器而异 | +| | @zereight/mcp-gitlab | GitLab MCP A（社区 CQRS 型） | GitLab 官方 MCP 服务器 | +| ------------ | -------------------------------------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | +| **更适合** | AI 代理工作流 | 企业多实例 / 分组工具 | 内置于 GitLab，无需单独安装 | +| **工具模型** | 274 个工具：toolset 中 272 个 + `execute_graphql` + `discover_tools` | ~50–60 个 `browse_*` / `manage_*` 分组工具 | 用 HTTP 头选择 toolset | +| **MR 审查** | 两步批量 diff | 因服务器而异 | `get_merge_request` 带 diffs | +| **Node.js** | >=18.17 | 通常 >=24 | stdio 经 `mcp-remote`，需要 Node.js 20+ | +| **许可证** | MIT | 因服务器而异 | GitLab 的一部分 | + +[与 GitLab MCP A 的完整对比 →](./docs/comparison/community-gitlab-mcp-a.md) + +GitLab 还提供[官方 MCP 服务器](https://docs.gitlab.com/user/model_context_protocol/mcp_server/)。 -[完整对比 →](./docs/comparison/community-gitlab-mcp-a.md) +- Free、Premium、Ultimate。GitLab 19.2 从 Premium 移到 Free。GitLab 19.5 正式可用。 +- 在 GitLab.com 上，顶级群组 Owner 允许访问 MCP 服务器。GitLab Self-Managed 和 GitLab Dedicated 使用实例设置。默认规则见官方页面。 +- 远程客户端使用 HTTP `https:///api/v4/mcp` 和 OAuth 2.0 动态客户端注册。 +- stdio 通过 `mcp-remote`，需要 Node.js 20 或更高版本。 +- Toolset 使用请求头 `X-Gitlab-Enabled-Mcp-Server-Toolsets`。可选请求头 `X-Gitlab-Mcp-Server-Tool-Name-Prefix` 只保留工具名前缀的前 32 个字符。 快速开始：在下面选择 Personal Access Token 或 OAuth2 设置，安装 `@zereight/mcp-gitlab`，并在 MCP 客户端配置中使用 `zereight-mcp-gitlab`。 diff --git a/docs/comparison/community-gitlab-mcp-a.md b/docs/comparison/community-gitlab-mcp-a.md index c97cf9122..4adb24833 100644 --- a/docs/comparison/community-gitlab-mcp-a.md +++ b/docs/comparison/community-gitlab-mcp-a.md @@ -94,7 +94,7 @@ unverified. | Auto schema filtering by GitLab edition/tier | `@structured-world/gitlab-mcp` | High | | MCP prompts/resources as first-class primitives (not just tools) | `python-gitlab-mcp` (PyPI) | Medium | | GraphQL API option alongside REST | `vish288/mcp-gitlab`, `jmrplens/gitlab-mcp-server` | Low–Medium (tool-count claims unverified) | -| OAuth Dynamic Client Registration (self-register against the GitLab instance, no manual app setup) | Official GitLab MCP (Premium/Ultimate, Beta) | Medium | +| OAuth Dynamic Client Registration (self-register against the GitLab instance, no manual app setup) | Official GitLab MCP (Free, Premium, and Ultimate, generally available in GitLab 19.5) | Medium | Note: protected branches (`list_protected_branches`, `get_protected_branch`, `protect_branch`, `unprotect_branch`) were already covered by `yoda-digital/mcp-gitlab-server` at survey time — we diff --git a/docs/comparison/index.md b/docs/comparison/index.md index 0d06757a8..5e662df46 100644 --- a/docs/comparison/index.md +++ b/docs/comparison/index.md @@ -19,6 +19,7 @@ servers. - [GitLab MCP A (community CQRS-style)](community-gitlab-mcp-a.md) — architectural comparison against grouped read/write tool models +- GitLab's [official MCP server](https://docs.gitlab.com/user/model_context_protocol/mcp_server/) ships inside GitLab. Free, Premium, and Ultimate. Generally available in GitLab 19.5. ## Choosing @zereight/mcp-gitlab From b88faa530daf354db7c7c8566e3cc8be4e4cb551 Mon Sep 17 00:00:00 2001 From: zereight Date: Mon, 12 Oct 2026 10:43:17 +0900 Subject: [PATCH 2/2] docs(comparison): qualify official MCP DCR when an admin disables it Self-Managed and Dedicated can turn dynamic client registration off, and clients then need a pre-registered OAuth application. Co-authored-by: Cursor --- docs/comparison/community-gitlab-mcp-a.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/comparison/community-gitlab-mcp-a.md b/docs/comparison/community-gitlab-mcp-a.md index 4adb24833..30be12f13 100644 --- a/docs/comparison/community-gitlab-mcp-a.md +++ b/docs/comparison/community-gitlab-mcp-a.md @@ -94,7 +94,7 @@ unverified. | Auto schema filtering by GitLab edition/tier | `@structured-world/gitlab-mcp` | High | | MCP prompts/resources as first-class primitives (not just tools) | `python-gitlab-mcp` (PyPI) | Medium | | GraphQL API option alongside REST | `vish288/mcp-gitlab`, `jmrplens/gitlab-mcp-server` | Low–Medium (tool-count claims unverified) | -| OAuth Dynamic Client Registration (self-register against the GitLab instance, no manual app setup) | Official GitLab MCP (Free, Premium, and Ultimate, generally available in GitLab 19.5) | Medium | +| OAuth Dynamic Client Registration (self-register by default. A pre-registered OAuth application is required if an administrator turns DCR off on Self-Managed or Dedicated) | Official GitLab MCP (Free, Premium, and Ultimate, generally available in GitLab 19.5) | Medium | Note: protected branches (`list_protected_branches`, `get_protected_branch`, `protect_branch`, `unprotect_branch`) were already covered by `yoda-digital/mcp-gitlab-server` at survey time — we