@zereight/mcp-gitlab 2.3.8-next.145 → 2.3.8-next.147
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.ko.md +117 -15
- package/README.md +120 -16
- package/README.pt-BR.md +117 -15
- package/README.zh-CN.md +117 -15
- package/build/index.js +70 -10
- package/build/schemas.js +4 -0
- package/build/server/mcp-help.js +101 -0
- package/build/server/mcp-instructions.js +14 -0
- package/build/tools/discover-activation.js +5 -4
- package/build/tools/exposed-tools.js +11 -5
- package/build/tools/listed-tools.js +20 -1
- package/build/tools/registry.js +7 -0
- package/build/tools/tool-descriptions.js +1 -0
- package/build/utils/error-hints.js +42 -0
- package/build/utils/list-summary.js +90 -0
- package/package.json +1 -1
package/README.ko.md
CHANGED
|
@@ -1,30 +1,132 @@
|
|
|
1
1
|
# GitLab MCP Server
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/@zereight/mcp-gitlab)
|
|
4
|
-
[](https://vscode.dev/redirect/mcp/install?name=zereight.gitlab-mcp&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22gitlab-token%22%2C%22description%22%3A%22GitLab%20Personal%20Access%20Token%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40zereight%2Fmcp-gitlab%40latest%22%5D%2C%22env%22%3A%7B%22GITLAB_PERSONAL_ACCESS_TOKEN%22%3A%22%24%7Binput%3Agitlab-token%7D%22%2C%22GITLAB_API_URL%22%3A%22https%3A%2F%2Fgitlab.com%2Fapi%2Fv4%22%7D%7D)
|
|
5
|
-
[](https://cursor.com/en/install-mcp?name=zereight.gitlab-mcp&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB6ZXJlaWdodC9tY3AtZ2l0bGFiQGxhdGVzdCJdLCJlbnYiOnsiR0lUTEFCX1BFUlNPTkFMX0FDQ0VTU19UT0tFTiI6IiR7ZW52OkdJVExBQl9QRVJTT05BTF9BQ0NFU1NfVE9LRU59IiwiR0lUTEFCX0FQSV9VUkwiOiJodHRwczovL2dpdGxhYi5jb20vYXBpL3Y0In19)
|
|
6
4
|
|
|
7
5
|
[English](./README.md) | [한국어](./README.ko.md) | [简体中文](./README.zh-CN.md) | [Português (Brasil)](./README.pt-BR.md)
|
|
8
6
|
|
|
9
|
-
📖 **[문서 →](https://zereight.github.io/gitlab-mcp/)**
|
|
7
|
+
📖 **[문서 →](https://zereight.github.io/gitlab-mcp/)** · [llms.txt](./llms.txt) · [llms-full.txt](./llms-full.txt)
|
|
10
8
|
|
|
11
|
-
|
|
9
|
+
**기본 노출: 40개 도구** (`core` 38개 + `discover_tools` + `help`). 전체는 278개(toolset 275개 + `execute_graphql` + `discover_tools` + `help`). 작게 시작하고, 세션에서 `discover_tools`로 확장하세요.
|
|
12
10
|
|
|
13
11
|
`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`. 공식 MCP Registry 항목: [`io.github.zereight/gitlab-mcp`](https://registry.modelcontextprotocol.io/?q=io.github.zereight%2Fgitlab-mcp). 한 줄 설치: `npx -y @zereight/mcp-gitlab@latest`.
|
|
14
12
|
|
|
15
|
-
|
|
13
|
+
### Without → With
|
|
14
|
+
|
|
15
|
+
| 이 MCP 없이 | 이 MCP로 |
|
|
16
|
+
| ----------- | -------- |
|
|
17
|
+
| MR URL과 diff를 채팅에 붙여넣기 | `list_merge_request_changed_files` → 배치 `get_merge_request_file_diff` |
|
|
18
|
+
| GitLab UI에서 job 로그 찾기 | 페이지네이션과 함께 `get_pipeline_job_output` |
|
|
19
|
+
| 매 턴마다 프로젝트 경로를 다시 설명 | `project_id=group%2Fproject`, `merge_request_iid=123` |
|
|
20
|
+
|
|
21
|
+
### 설치 3경로
|
|
22
|
+
|
|
23
|
+
| 경로 | 언제 | 어떻게 |
|
|
24
|
+
| ---- | ---- | ------ |
|
|
25
|
+
| 로컬 IDE | 내 머신의 Cursor, Claude Code, Codex | stdio + PAT 또는 로컬 OAuth |
|
|
26
|
+
| 공유 HTTP | 팀 / 호스팅 MCP | Streamable HTTP URL + 원격 인증 또는 MCP OAuth |
|
|
27
|
+
| Claude.ai | Claude 웹 커넥터 | 공개 HTTPS + `GITLAB_MCP_OAUTH` |
|
|
28
|
+
|
|
29
|
+
### 설치
|
|
30
|
+
|
|
31
|
+
[](https://cursor.com/en/install-mcp?name=zereight.gitlab-mcp&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB6ZXJlaWdodC9tY3AtZ2l0bGFiQGxhdGVzdCJdLCJlbnYiOnsiR0lUTEFCX1BFUlNPTkFMX0FDQ0VTU19UT0tFTiI6IiR7ZW52OkdJVExBQl9QRVJTT05BTF9BQ0NFU1NfVE9LRU59IiwiR0lUTEFCX0FQSV9VUkwiOiJodHRwczovL2dpdGxhYi5jb20vYXBpL3Y0In19)
|
|
32
|
+
|
|
33
|
+
바이너리를 먼저 설치하세요 (`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`). 토큰은 화면에 표시하지 않고 읽으세요:
|
|
16
34
|
|
|
17
35
|
```bash
|
|
18
36
|
read -rs GITLAB_PERSONAL_ACCESS_TOKEN && export GITLAB_PERSONAL_ACCESS_TOKEN
|
|
19
37
|
```
|
|
20
38
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
39
|
+
```bash
|
|
40
|
+
# Claude Code
|
|
41
|
+
claude mcp add gitlab --transport stdio --scope local --env GITLAB_PERSONAL_ACCESS_TOKEN="$GITLAB_PERSONAL_ACCESS_TOKEN" --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab
|
|
42
|
+
|
|
43
|
+
# Codex
|
|
44
|
+
codex mcp add gitlab --env GITLAB_PERSONAL_ACCESS_TOKEN="$GITLAB_PERSONAL_ACCESS_TOKEN" --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
다른 클라이언트: [VS Code](./docs/clients/vscode.md) · [GitHub Copilot](./docs/clients/copilot.md) · [JSON 클라이언트](./docs/clients/json-clients.md) · [Cursor 상세](./docs/clients/cursor.md)
|
|
48
|
+
|
|
49
|
+
### 에이전트용 붙여넣기 프롬프트
|
|
50
|
+
|
|
51
|
+
MCP 설정을 고칠 수 있는 에이전트에 그대로 붙여넣으세요:
|
|
52
|
+
|
|
53
|
+
```
|
|
54
|
+
이 워크스페이스에 GitLab MCP 서버(@zereight/mcp-gitlab)를 설치하세요.
|
|
55
|
+
바이너리: zereight-mcp-gitlab (npm i -g @zereight/mcp-gitlab, 또는 npx -y @zereight/mcp-gitlab@latest).
|
|
56
|
+
인증: GITLAB_PERSONAL_ACCESS_TOKEN 과 GITLAB_API_URL=https://gitlab.com/api/v4 (또는 GITLAB_USE_OAUTH=true).
|
|
57
|
+
로컬: claude mcp add gitlab --transport stdio --scope local --env GITLAB_PERSONAL_ACCESS_TOKEN="$GITLAB_PERSONAL_ACCESS_TOKEN" --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab
|
|
58
|
+
또는: codex mcp add gitlab --env GITLAB_PERSONAL_ACCESS_TOKEN="$GITLAB_PERSONAL_ACCESS_TOKEN" --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab
|
|
59
|
+
Cursor: README deeplink 또는 docs/clients/cursor.md.
|
|
60
|
+
원격 HTTP: 클라이언트를 https://mcp.example.com/mcp (Streamable HTTP)로 연결. Claude.ai는 그 호스트에 GITLAB_MCP_OAUTH가 필요합니다.
|
|
61
|
+
기본 목록: 40개 도구(core 38 + discover_tools + help). 확장은 discover_tools. api toolset은 우회 위험을 받아들일 때만.
|
|
62
|
+
MCP 없는 동등 경로: npx skills add zereight/gitlab-mcp --skill gitlab-mcp-skill 와 zereight-mcp-gitlab CLI.
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
### 원격 HTTP
|
|
66
|
+
|
|
67
|
+
호스팅/셀프호스트 서버의 1순위 옵션입니다. 클라이언트를 Streamable HTTP URL로 연결하세요:
|
|
68
|
+
|
|
69
|
+
```json
|
|
70
|
+
{
|
|
71
|
+
"mcpServers": {
|
|
72
|
+
"gitlab": {
|
|
73
|
+
"type": "http",
|
|
74
|
+
"url": "https://mcp.example.com/mcp"
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
- 호스팅 / Claude.ai: 서버에서 `GITLAB_MCP_OAUTH=true` ([MCP OAuth](#mcp-oauth-프록시-사용하기-gitlab_mcp_oauth) 참고)
|
|
81
|
+
- 사용자별 PAT 헤더: `REMOTE_AUTHORIZATION=true` ([원격 인증](#원격-인증-사용하기-remote_authorization) 참고)
|
|
82
|
+
- 로컬 Docker 예시는 [사용법](#사용법)에 있습니다
|
|
83
|
+
|
|
84
|
+
### Skill + CLI (MCP 불필요)
|
|
85
|
+
|
|
86
|
+
Skill + CLI는 폴백이 아니라 동등한 경로입니다. 같은 워크플로우, 터미널의 전체 페이로드, MCP 등록 없음.
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
npx skills add zereight/gitlab-mcp --skill gitlab-mcp-skill
|
|
90
|
+
zereight-mcp-gitlab user whoami
|
|
91
|
+
zereight-mcp-gitlab mr list
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
[MCP 없이 CLI](./docs/getting-started/cli-without-mcp.md)와 [`skills/gitlab-mcp/`](./skills/gitlab-mcp/)를 보세요.
|
|
95
|
+
|
|
96
|
+
### MCP vs Human CLI
|
|
97
|
+
|
|
98
|
+
| MCP를 쓸 때 | CLI를 쓸 때 |
|
|
99
|
+
| ----------- | ----------- |
|
|
100
|
+
| 채팅에서 구조화된 도구가 필요할 때 | 전체 페이로드(diff, 로그, 아티팩트)가 필요할 때 |
|
|
101
|
+
| `jmespath`나 compact 결과로 충분할 때 | `GITLAB_MCP_COMPACT_RESULTS`가 켜져 있고 나머지는 터미널에서 볼 때 |
|
|
102
|
+
| 이미 MCP 서버를 등록했을 때 | PAT가 있거나 `auth`를 했고 MCP가 필요 없을 때 |
|
|
103
|
+
|
|
104
|
+
Human CLI는 compact되지 않습니다. 파괴적 도구와 `GITLAB_TOOL_POLICY_APPROVE` 도구는 `--yes`가 필요합니다.
|
|
105
|
+
|
|
106
|
+
### Tips
|
|
107
|
+
|
|
108
|
+
`project_id`는 숫자 ID 또는 URL 인코딩된 경로입니다. 예: 그룹 `group`, 프로젝트 `project`, MR `!123` → `project_id=group%2Fproject`, `merge_request_iid=123`. 중첩 그룹은 세그먼트마다 `%2F`를 씁니다 (`group%2Fsubgroup%2Fproject`).
|
|
109
|
+
|
|
110
|
+
### FAQ
|
|
111
|
+
|
|
112
|
+
**인증은 어떻게 하나요?** 로컬 데스크톱은 `GITLAB_PERSONAL_ACCESS_TOKEN`(또는 `GITLAB_PERSONAL_ACCESS_TOKEN_FILE`)이 가장 단순합니다. 로컬 OAuth는 `GITLAB_USE_OAUTH=true`. 원격 Claude.ai는 `GITLAB_MCP_OAUTH`. 멀티유저 HTTP는 `REMOTE_AUTHORIZATION`과 요청별 토큰 헤더입니다.
|
|
113
|
+
|
|
114
|
+
**도구가 40개만 보이는 이유는?** 기본 `core` toolset 38개에 항상 켜진 `discover_tools`와 `help`가 더해집니다. 인자 없이 `discover_tools`를 호출하면 카테고리 목록이 나오고, 카테고리(`pipelines`, `wiki` 등)를 넘기면 이 세션에 활성화됩니다. `GITLAB_TOOLSETS=all`도 `api`는 켜지 않습니다.
|
|
115
|
+
|
|
116
|
+
**로컬 OAuth / MCP OAuth / 원격 인증 차이는?** 로컬 OAuth는 서버와 같은 머신에서 브라우저를 엽니다. MCP OAuth는 공개 HTTPS 서버와 Claude.ai 같은 클라이언트용입니다. 원격 인증은 호출자의 PAT 또는 job token을 전달하며 OAuth 흐름이 없습니다.
|
|
117
|
+
|
|
118
|
+
**큰 응답을 줄이려면?** 도구 호출에 `jmespath`를 넘기세요. 또는 `GITLAB_MCP_COMPACT_RESULTS=true`로 큰 MCP 응답을 미리보기 + CLI 명령으로 바꿉니다. 전체 페이로드가 필요하면 CLI를 쓰세요.
|
|
119
|
+
|
|
120
|
+
**`api` toolset이 위험한 이유는?** `gitlab_api_request`는 그룹/프로젝트 허용 목록, 다른 도구 필터, 도구별 안전 검사를 우회합니다. 프롬프트 인젝션이 이 도구를 구동할 수 있습니다. `GITLAB_TOOLSETS`에 `api`를 직접 넣을 때만 켜세요. `all`, `discover_tools`, `GITLAB_TOOLS`는 켜지 않습니다.
|
|
121
|
+
|
|
122
|
+
### Cursor rule / CLAUDE.md 스니펫
|
|
123
|
+
|
|
124
|
+
```
|
|
125
|
+
GitLab 머지 리퀘스트, 이슈, 파이프라인은 이 MCP(@zereight/mcp-gitlab)로 처리하세요.
|
|
126
|
+
기본 core 도구로 시작하고, 확장은 discover_tools를 호출하세요.
|
|
127
|
+
list_merge_request_changed_files 다음 배치 get_merge_request_file_diff를 우선하세요.
|
|
128
|
+
결과는 jmespath 또는 compact를 쓰고, 전체 diff와 job 로그는 CLI를 쓰세요.
|
|
129
|
+
```
|
|
28
130
|
|
|
29
131
|
[](https://www.star-history.com/?repos=zereight%2Fgitlab-mcp&type=date&legend=top-left)
|
|
30
132
|
|
|
@@ -36,7 +138,7 @@ PAT, OAuth, 읽기 전용 모드, 동적 API URL, 원격 인증을 지원하며
|
|
|
36
138
|
|
|
37
139
|
### 왜 이 GitLab MCP를 사용하나요?
|
|
38
140
|
|
|
39
|
-
-
|
|
141
|
+
- **기본 40개 도구(`core` 38 + `discover_tools` + `help`); 전체 278개** — 작게 시작하고, `discover_tools`로 세션에서 확장
|
|
40
142
|
- **MR 2단계 리뷰** — `list_merge_request_changed_files` → 배치 `get_merge_request_file_diff`
|
|
41
143
|
- **Agent Skill 내장** — `skills/gitlab-mcp/` 워크플로우 가이드
|
|
42
144
|
- **유연한 인증** — Personal Access Token, 로컬 OAuth2 브라우저 플로우, MCP OAuth 프록시, 요청별 원격 인증
|
|
@@ -50,7 +152,7 @@ PAT, OAuth, 읽기 전용 모드, 동적 API URL, 원격 인증을 지원하며
|
|
|
50
152
|
| | @zereight/mcp-gitlab | GitLab MCP A (커뮤니티 CQRS형) | GitLab 공식 MCP 서버 |
|
|
51
153
|
| --------------- | ---------------------------------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
52
154
|
| **적합한 경우** | AI 에이전트 워크플로우 | 엔터프라이즈 멀티 인스턴스 / 그룹형 도구 | GitLab에 내장, 별도 설치 없음 |
|
|
53
|
-
| **도구 모델** |
|
|
155
|
+
| **도구 모델** | 278개 도구: toolset 275개 + `execute_graphql` + `discover_tools` + `help` | ~50–60개 `browse_*` / `manage_*` 그룹 도구 | HTTP 헤더로 고르는 toolset |
|
|
54
156
|
| **MR 리뷰** | 2단계 배치 diff | 서버마다 다름 | `get_merge_request`에 diffs |
|
|
55
157
|
| **Node.js** | >=18.17 | 보통 >=24 | stdio는 `mcp-remote`, Node.js 20+ |
|
|
56
158
|
| **라이선스** | MIT | 서버마다 다름 | GitLab의 일부 |
|
|
@@ -603,7 +705,7 @@ node build/index.js
|
|
|
603
705
|
|
|
604
706
|
## Agent Skill Files
|
|
605
707
|
|
|
606
|
-
AI 에이전트가 skill/instruction 로딩을 지원하는 경우(Claude Code, GitHub Copilot, Cursor 등), [`skills/gitlab-mcp/`](./skills/gitlab-mcp/)에 미리 작성된 skill 파일을 사용할 수 있습니다.
|
|
708
|
+
Skill + CLI는 MCP와 동등한 경로입니다([Skill + CLI](#skill--cli-mcp-불필요) 참고). AI 에이전트가 skill/instruction 로딩을 지원하는 경우(Claude Code, GitHub Copilot, Cursor 등), [`skills/gitlab-mcp/`](./skills/gitlab-mcp/)에 미리 작성된 skill 파일을 사용할 수 있습니다.
|
|
607
709
|
|
|
608
710
|
- **[SKILL.md](./skills/gitlab-mcp/SKILL.md)** — 도구셋 개요, 핵심 워크플로우, 파라미터 힌트를 담은 핵심 가이드
|
|
609
711
|
- **[reference/](./skills/gitlab-mcp/reference/)** — 코드 리뷰, 머지 리퀘스트, 이슈, 파이프라인, 취약점 트리아지용 상세 워크플로우 문서
|
package/README.md
CHANGED
|
@@ -4,32 +4,135 @@
|
|
|
4
4
|
[](https://www.npmjs.com/package/@zereight/mcp-gitlab)
|
|
5
5
|
[](https://www.npmjs.com/package/@zereight/mcp-gitlab)
|
|
6
6
|
[](https://github.com/zereight/gitlab-mcp/blob/main/LICENSE)
|
|
7
|
-
[](https://vscode.dev/redirect/mcp/install?name=zereight.gitlab-mcp&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22gitlab-token%22%2C%22description%22%3A%22GitLab%20Personal%20Access%20Token%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40zereight%2Fmcp-gitlab%40latest%22%5D%2C%22env%22%3A%7B%22GITLAB_PERSONAL_ACCESS_TOKEN%22%3A%22%24%7Binput%3Agitlab-token%7D%22%2C%22GITLAB_API_URL%22%3A%22https%3A%2F%2Fgitlab.com%2Fapi%2Fv4%22%7D%7D)
|
|
8
|
-
[](https://cursor.com/en/install-mcp?name=zereight.gitlab-mcp&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB6ZXJlaWdodC9tY3AtZ2l0bGFiQGxhdGVzdCJdLCJlbnYiOnsiR0lUTEFCX1BFUlNPTkFMX0FDQ0VTU19UT0tFTiI6IiR7ZW52OkdJVExBQl9QRVJTT05BTF9BQ0NFU1NfVE9LRU59IiwiR0lUTEFCX0FQSV9VUkwiOiJodHRwczovL2dpdGxhYi5jb20vYXBpL3Y0In19)
|
|
9
7
|
[](https://deepwiki.com/zereight/gitlab-mcp)
|
|
10
|
-
[](https://mcptoplist.com/server/io.github.zereight%2Fgitlab-mcp)
|
|
8
|
+
[](https://mcptoplist.com/server/io.github.zereight%2Fgitlab-mcp)
|
|
9
|
+
[](https://mcpindex.ai/server/io-github-zereight-gitlab-mcp)
|
|
11
10
|
|
|
12
11
|
[English](./README.md) | [한국어](./README.ko.md) | [简体中文](./README.zh-CN.md) | [Português (Brasil)](./README.pt-BR.md)
|
|
13
12
|
|
|
14
|
-
📖 **[Documentation →](https://zereight.github.io/gitlab-mcp/)**
|
|
13
|
+
📖 **[Documentation →](https://zereight.github.io/gitlab-mcp/)** · [llms.txt](./llms.txt) · [llms-full.txt](./llms-full.txt)
|
|
15
14
|
|
|
16
|
-
|
|
15
|
+
**Default: 40 tools** (38 `core` + `discover_tools` + `help`). 278 tools exist in total (275 in toolsets + `execute_graphql` + `discover_tools` + `help`). Start lean; call `discover_tools` to activate more for this session.
|
|
17
16
|
|
|
18
17
|
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`. Official MCP Registry listing: [`io.github.zereight/gitlab-mcp`](https://registry.modelcontextprotocol.io/?q=io.github.zereight%2Fgitlab-mcp). One-liner: `npx -y @zereight/mcp-gitlab@latest`.
|
|
19
18
|
|
|
20
|
-
|
|
19
|
+
### Without → With
|
|
20
|
+
|
|
21
|
+
| Without this MCP | With this MCP |
|
|
22
|
+
| ---------------- | ------------- |
|
|
23
|
+
| Paste MR URLs and diffs into chat | `list_merge_request_changed_files` → batched `get_merge_request_file_diff` |
|
|
24
|
+
| Hunt job logs in the GitLab UI | `get_pipeline_job_output` with pagination |
|
|
25
|
+
| Re-explain the project path every turn | `project_id=group%2Fproject` and `merge_request_iid=123` |
|
|
26
|
+
|
|
27
|
+
### Three install paths
|
|
28
|
+
|
|
29
|
+
| Path | When | How |
|
|
30
|
+
| ---- | ---- | --- |
|
|
31
|
+
| Local IDE | Cursor, Claude Code, Codex on your machine | stdio + PAT or local OAuth |
|
|
32
|
+
| Shared HTTP | Team or hosted MCP | Streamable HTTP URL + remote auth or MCP OAuth |
|
|
33
|
+
| Claude.ai | Claude web connectors | Public HTTPS + `GITLAB_MCP_OAUTH` |
|
|
34
|
+
|
|
35
|
+
### Install
|
|
36
|
+
|
|
37
|
+
[](https://cursor.com/en/install-mcp?name=zereight.gitlab-mcp&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB6ZXJlaWdodC9tY3AtZ2l0bGFiQGxhdGVzdCJdLCJlbnYiOnsiR0lUTEFCX1BFUlNPTkFMX0FDQ0VTU19UT0tFTiI6IiR7ZW52OkdJVExBQl9QRVJTT05BTF9BQ0NFU1NfVE9LRU59IiwiR0lUTEFCX0FQSV9VUkwiOiJodHRwczovL2dpdGxhYi5jb20vYXBpL3Y0In19)
|
|
38
|
+
|
|
39
|
+
Install the binary first (`npm install -g @zereight/mcp-gitlab`, or Homebrew `brew tap zereight/gitlab-mcp https://github.com/zereight/gitlab-mcp` then `brew install zereight/gitlab-mcp/zereight-mcp-gitlab`). Read the token without echo:
|
|
21
40
|
|
|
22
41
|
```bash
|
|
23
42
|
read -rs GITLAB_PERSONAL_ACCESS_TOKEN && export GITLAB_PERSONAL_ACCESS_TOKEN
|
|
24
43
|
```
|
|
25
44
|
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
45
|
+
```bash
|
|
46
|
+
# Claude Code
|
|
47
|
+
claude mcp add gitlab --transport stdio --scope local --env GITLAB_PERSONAL_ACCESS_TOKEN="$GITLAB_PERSONAL_ACCESS_TOKEN" --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab
|
|
48
|
+
|
|
49
|
+
# Codex
|
|
50
|
+
codex mcp add gitlab --env GITLAB_PERSONAL_ACCESS_TOKEN="$GITLAB_PERSONAL_ACCESS_TOKEN" --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
Other clients: [VS Code](./docs/clients/vscode.md) · [GitHub Copilot](./docs/clients/copilot.md) · [JSON clients](./docs/clients/json-clients.md) · [Cursor details](./docs/clients/cursor.md)
|
|
54
|
+
|
|
55
|
+
### Agent paste-prompt
|
|
56
|
+
|
|
57
|
+
Copy this into an agent that can edit MCP config:
|
|
58
|
+
|
|
59
|
+
```
|
|
60
|
+
Install the GitLab MCP server (@zereight/mcp-gitlab) for this workspace.
|
|
61
|
+
Binary: zereight-mcp-gitlab (npm i -g @zereight/mcp-gitlab, or npx -y @zereight/mcp-gitlab@latest).
|
|
62
|
+
Auth: GITLAB_PERSONAL_ACCESS_TOKEN plus GITLAB_API_URL=https://gitlab.com/api/v4 (or GITLAB_USE_OAUTH=true).
|
|
63
|
+
Local: claude mcp add gitlab --transport stdio --scope local --env GITLAB_PERSONAL_ACCESS_TOKEN="$GITLAB_PERSONAL_ACCESS_TOKEN" --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab
|
|
64
|
+
Or: codex mcp add gitlab --env GITLAB_PERSONAL_ACCESS_TOKEN="$GITLAB_PERSONAL_ACCESS_TOKEN" --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab
|
|
65
|
+
Cursor: use the README deeplink or docs/clients/cursor.md.
|
|
66
|
+
Remote HTTP: point the client at https://mcp.example.com/mcp (Streamable HTTP). Claude.ai needs GITLAB_MCP_OAUTH on that host.
|
|
67
|
+
Default list: 40 tools (38 core + discover_tools + help). Call discover_tools to expand. Do not enable the api toolset unless you accept its bypass risk.
|
|
68
|
+
Equal non-MCP path: npx skills add zereight/gitlab-mcp --skill gitlab-mcp-skill plus the zereight-mcp-gitlab CLI.
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
### Remote HTTP
|
|
72
|
+
|
|
73
|
+
First-class option for a hosted or self-hosted server. Point the client at a Streamable HTTP URL:
|
|
74
|
+
|
|
75
|
+
```json
|
|
76
|
+
{
|
|
77
|
+
"mcpServers": {
|
|
78
|
+
"gitlab": {
|
|
79
|
+
"type": "http",
|
|
80
|
+
"url": "https://mcp.example.com/mcp"
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
- Hosted / Claude.ai: `GITLAB_MCP_OAUTH=true` on the server (see [MCP OAuth](#mcp-oauth-setup-claudeai-native-oauth))
|
|
87
|
+
- Per-user PAT headers: `REMOTE_AUTHORIZATION=true` (see [Remote Authorization](#using-remote-authorization-remote_authorization))
|
|
88
|
+
- Local Docker examples are in [Usage](#usage)
|
|
89
|
+
|
|
90
|
+
### Skill + CLI (no MCP required)
|
|
91
|
+
|
|
92
|
+
Skill + CLI is an equal path, not a fallback. Same workflows, full payloads in a terminal, no MCP registration.
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
npx skills add zereight/gitlab-mcp --skill gitlab-mcp-skill
|
|
96
|
+
zereight-mcp-gitlab user whoami
|
|
97
|
+
zereight-mcp-gitlab mr list
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
See [CLI without MCP](./docs/getting-started/cli-without-mcp.md) and [`skills/gitlab-mcp/`](./skills/gitlab-mcp/).
|
|
101
|
+
|
|
102
|
+
### MCP vs Human CLI
|
|
103
|
+
|
|
104
|
+
| Use MCP when | Use the CLI when |
|
|
105
|
+
| ------------ | ---------------- |
|
|
106
|
+
| The agent needs structured tools in chat | You need the full payload (diffs, logs, artifacts) |
|
|
107
|
+
| `jmespath` or compact results are enough | `GITLAB_MCP_COMPACT_RESULTS` is on and you want the rest in a terminal |
|
|
108
|
+
| You already registered the server | You have a PAT or ran `auth` and do not want MCP |
|
|
109
|
+
|
|
110
|
+
Human CLI is never compacted. Destructive tools and `GITLAB_TOOL_POLICY_APPROVE` tools need `--yes`.
|
|
111
|
+
|
|
112
|
+
### Tips
|
|
113
|
+
|
|
114
|
+
`project_id` is a numeric ID or a URL-encoded path. Example: group `group`, project `project`, merge request `!123` → `project_id=group%2Fproject`, `merge_request_iid=123`. Nested groups use `%2F` between every segment (`group%2Fsubgroup%2Fproject`).
|
|
115
|
+
|
|
116
|
+
### FAQ
|
|
117
|
+
|
|
118
|
+
**How do I authenticate?** Local desktop: `GITLAB_PERSONAL_ACCESS_TOKEN` (or `GITLAB_PERSONAL_ACCESS_TOKEN_FILE`) is the simplest. Local OAuth is `GITLAB_USE_OAUTH=true`. Remote Claude.ai uses `GITLAB_MCP_OAUTH`. Multi-user HTTP uses `REMOTE_AUTHORIZATION` and a per-request token header.
|
|
119
|
+
|
|
120
|
+
**Why do I only see ~40 tools?** The default `core` toolset is 38 tools plus always-on `discover_tools` and `help`. Call `discover_tools` with no args to list categories, then pass a category (`pipelines`, `wiki`, …) to activate it for this session. `GITLAB_TOOLSETS=all` still does **not** enable `api`.
|
|
121
|
+
|
|
122
|
+
**Local OAuth vs MCP OAuth vs remote auth?** Local OAuth opens a browser on the same machine as the server. MCP OAuth is for a public HTTPS server and clients such as Claude.ai. Remote authorization forwards the caller's PAT or job token; there is no OAuth dance.
|
|
123
|
+
|
|
124
|
+
**How do I shrink huge replies?** Pass `jmespath` on any tool call. Or set `GITLAB_MCP_COMPACT_RESULTS=true` so oversized MCP replies become a preview plus a CLI command. Use the CLI when you need the full payload.
|
|
125
|
+
|
|
126
|
+
**Why is the `api` toolset dangerous?** `gitlab_api_request` bypasses group/project allowlists, other tool filters, and per-tool safety checks. Prompt injection can drive it. Enable it only by listing `api` in `GITLAB_TOOLSETS`. `all`, `discover_tools`, and `GITLAB_TOOLS` do not.
|
|
127
|
+
|
|
128
|
+
### Cursor rule / CLAUDE.md snippet
|
|
129
|
+
|
|
130
|
+
```
|
|
131
|
+
GitLab merge requests, issues, and pipelines go through this MCP (@zereight/mcp-gitlab).
|
|
132
|
+
Start with the default core tools. Call discover_tools to expand.
|
|
133
|
+
Prefer list_merge_request_changed_files, then batched get_merge_request_file_diff.
|
|
134
|
+
Use jmespath or compact results; use the CLI for full diffs and job logs.
|
|
135
|
+
```
|
|
33
136
|
|
|
34
137
|
[](https://www.star-history.com/?repos=zereight%2Fgitlab-mcp&type=date&legend=top-left)
|
|
35
138
|
|
|
@@ -41,7 +144,7 @@ Supports PAT, OAuth, read-only mode, dynamic API URLs, and remote authorization
|
|
|
41
144
|
|
|
42
145
|
### Why use this GitLab MCP?
|
|
43
146
|
|
|
44
|
-
- **
|
|
147
|
+
- **Default 40 tools (38 `core` + `discover_tools` + `help`); 278 total** — start lean; call `discover_tools` to activate more without CQRS-style grouping
|
|
45
148
|
- **MR 2-step review** — `list_merge_request_changed_files` → batched `get_merge_request_file_diff`
|
|
46
149
|
- **Agent Skill built in** — workflow guidance in `skills/gitlab-mcp/`
|
|
47
150
|
- **Flexible auth** — Personal Access Token, local OAuth2 browser flow, MCP OAuth proxy, and per-request remote authorization
|
|
@@ -55,7 +158,7 @@ Supports PAT, OAuth, read-only mode, dynamic API URLs, and remote authorization
|
|
|
55
158
|
| | @zereight/mcp-gitlab | GitLab MCP A (community CQRS-style) | GitLab official MCP server |
|
|
56
159
|
| -------------- | ----------------------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
57
160
|
| **Best for** | AI agent workflows | Enterprise multi-instance / grouped tools | Built into GitLab, no separate install |
|
|
58
|
-
| **Tool model** |
|
|
161
|
+
| **Tool model** | 278 tools: 275 in toolsets + `execute_graphql` + `discover_tools` + `help` | ~50–60 grouped `browse_*` / `manage_*` tools | Toolsets chosen with an HTTP header |
|
|
59
162
|
| **MR review** | 2-step batched diff | Varies | `get_merge_request` with diffs |
|
|
60
163
|
| **Node.js** | >=18.17 | Often >=24 | Node.js 20+ for stdio via `mcp-remote` |
|
|
61
164
|
| **License** | MIT | Varies | Part of GitLab |
|
|
@@ -653,7 +756,7 @@ No `headers` field is needed — Claude.ai obtains the token via OAuth automatic
|
|
|
653
756
|
|
|
654
757
|
## Agent Skill Files
|
|
655
758
|
|
|
656
|
-
Pre-built skill files are available in [`skills/gitlab-mcp/`](./skills/gitlab-mcp/) for AI agents that support skill/instruction loading (Claude Code, GitHub Copilot, Cursor, etc.).
|
|
759
|
+
Skill + CLI is an equal path to MCP (see [Skill + CLI](#skill--cli-no-mcp-required)). Pre-built skill files are available in [`skills/gitlab-mcp/`](./skills/gitlab-mcp/) for AI agents that support skill/instruction loading (Claude Code, GitHub Copilot, Cursor, etc.).
|
|
657
760
|
|
|
658
761
|
- **[SKILL.md](./skills/gitlab-mcp/SKILL.md)** — Core guide (~800 tokens) with toolset overview, key workflows, and parameter hints
|
|
659
762
|
- **[reference/](./skills/gitlab-mcp/reference/)** — Detailed workflow docs for code review, merge requests, issues, pipelines, and vulnerability triage
|
|
@@ -950,6 +1053,7 @@ Register the skill directory in your AI client to get optimal tool usage guidanc
|
|
|
950
1053
|
275. `rebase_merge_request` - Rebase the source branch of a merge request onto its target branch
|
|
951
1054
|
276. `gitlab_api_request` - Send one GitLab REST call under /api/v4. Enabled only when GITLAB_TOOLSETS lists api. Readonly allows GET; modify rejects DELETE.
|
|
952
1055
|
277. `discover_tools` - Discover and activate additional tool categories for this session. Available categories: core, merge_requests, issues, repositories, branches, projects, labels, ci, groups, pipelines, milestones, wiki, releases, tags, snippets, users, workitems, webhooks, search, variables, dependency_proxy, vulnerabilities, orbit. Already-active categories are listed in the response.
|
|
1056
|
+
278. `help` - Return a short GitLab workflow guide. Omit topic for the overview and topic list.
|
|
953
1057
|
|
|
954
1058
|
<!-- TOOLS-END -->
|
|
955
1059
|
|
package/README.pt-BR.md
CHANGED
|
@@ -1,30 +1,132 @@
|
|
|
1
1
|
# GitLab MCP Server
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/@zereight/mcp-gitlab)
|
|
4
|
-
[](https://vscode.dev/redirect/mcp/install?name=zereight.gitlab-mcp&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22gitlab-token%22%2C%22description%22%3A%22GitLab%20Personal%20Access%20Token%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40zereight%2Fmcp-gitlab%40latest%22%5D%2C%22env%22%3A%7B%22GITLAB_PERSONAL_ACCESS_TOKEN%22%3A%22%24%7Binput%3Agitlab-token%7D%22%2C%22GITLAB_API_URL%22%3A%22https%3A%2F%2Fgitlab.com%2Fapi%2Fv4%22%7D%7D)
|
|
5
|
-
[](https://cursor.com/en/install-mcp?name=zereight.gitlab-mcp&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB6ZXJlaWdodC9tY3AtZ2l0bGFiQGxhdGVzdCJdLCJlbnYiOnsiR0lUTEFCX1BFUlNPTkFMX0FDQ0VTU19UT0tFTiI6IiR7ZW52OkdJVExBQl9QRVJTT05BTF9BQ0NFU1NfVE9LRU59IiwiR0lUTEFCX0FQSV9VUkwiOiJodHRwczovL2dpdGxhYi5jb20vYXBpL3Y0In19)
|
|
6
4
|
|
|
7
5
|
[English](./README.md) | [한국어](./README.ko.md) | [简体中文](./README.zh-CN.md) | [Português (Brasil)](./README.pt-BR.md)
|
|
8
6
|
|
|
9
|
-
📖 **[Documentação →](https://zereight.github.io/gitlab-mcp/)**
|
|
7
|
+
📖 **[Documentação →](https://zereight.github.io/gitlab-mcp/)** · [llms.txt](./llms.txt) · [llms-full.txt](./llms-full.txt)
|
|
10
8
|
|
|
11
|
-
|
|
9
|
+
**Padrão: 40 ferramentas** (38 `core` + `discover_tools` + `help`). Existem 278 no total (275 em toolsets + `execute_graphql` + `discover_tools` + `help`). Comece enxuto; chame `discover_tools` para ativar mais nesta sessão.
|
|
12
10
|
|
|
13
11
|
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`. Listagem oficial no MCP Registry: [`io.github.zereight/gitlab-mcp`](https://registry.modelcontextprotocol.io/?q=io.github.zereight%2Fgitlab-mcp). Instalação em uma linha: `npx -y @zereight/mcp-gitlab@latest`.
|
|
14
12
|
|
|
15
|
-
|
|
13
|
+
### Without → With
|
|
14
|
+
|
|
15
|
+
| Sem este MCP | Com este MCP |
|
|
16
|
+
| ------------ | ------------ |
|
|
17
|
+
| Colar URLs e diffs de MR no chat | `list_merge_request_changed_files` → `get_merge_request_file_diff` em lote |
|
|
18
|
+
| Caçar logs de job na UI do GitLab | `get_pipeline_job_output` com paginação |
|
|
19
|
+
| Reexplicar o caminho do projeto a cada turno | `project_id=group%2Fproject` e `merge_request_iid=123` |
|
|
20
|
+
|
|
21
|
+
### Três caminhos de instalação
|
|
22
|
+
|
|
23
|
+
| Caminho | Quando | Como |
|
|
24
|
+
| ------- | ------ | ---- |
|
|
25
|
+
| IDE local | Cursor, Claude Code, Codex na sua máquina | stdio + PAT ou OAuth local |
|
|
26
|
+
| HTTP compartilhado | MCP de time ou hospedado | URL Streamable HTTP + auth remota ou MCP OAuth |
|
|
27
|
+
| Claude.ai | Conectores web do Claude | HTTPS público + `GITLAB_MCP_OAUTH` |
|
|
28
|
+
|
|
29
|
+
### Instalação
|
|
30
|
+
|
|
31
|
+
[](https://cursor.com/en/install-mcp?name=zereight.gitlab-mcp&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB6ZXJlaWdodC9tY3AtZ2l0bGFiQGxhdGVzdCJdLCJlbnYiOnsiR0lUTEFCX1BFUlNPTkFMX0FDQ0VTU19UT0tFTiI6IiR7ZW52OkdJVExBQl9QRVJTT05BTF9BQ0NFU1NfVE9LRU59IiwiR0lUTEFCX0FQSV9VUkwiOiJodHRwczovL2dpdGxhYi5jb20vYXBpL3Y0In19)
|
|
32
|
+
|
|
33
|
+
Instale o binário primeiro (`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`). Leia o token sem eco:
|
|
16
34
|
|
|
17
35
|
```bash
|
|
18
36
|
read -rs GITLAB_PERSONAL_ACCESS_TOKEN && export GITLAB_PERSONAL_ACCESS_TOKEN
|
|
19
37
|
```
|
|
20
38
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
39
|
+
```bash
|
|
40
|
+
# Claude Code
|
|
41
|
+
claude mcp add gitlab --transport stdio --scope local --env GITLAB_PERSONAL_ACCESS_TOKEN="$GITLAB_PERSONAL_ACCESS_TOKEN" --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab
|
|
42
|
+
|
|
43
|
+
# Codex
|
|
44
|
+
codex mcp add gitlab --env GITLAB_PERSONAL_ACCESS_TOKEN="$GITLAB_PERSONAL_ACCESS_TOKEN" --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Outros clientes: [VS Code](./docs/clients/vscode.md) · [GitHub Copilot](./docs/clients/copilot.md) · [Clientes JSON](./docs/clients/json-clients.md) · [Detalhes do Cursor](./docs/clients/cursor.md)
|
|
48
|
+
|
|
49
|
+
### Prompt para colar no agente
|
|
50
|
+
|
|
51
|
+
Cole isto em um agente que possa editar a config MCP:
|
|
52
|
+
|
|
53
|
+
```
|
|
54
|
+
Instale o servidor GitLab MCP (@zereight/mcp-gitlab) neste workspace.
|
|
55
|
+
Binário: zereight-mcp-gitlab (npm i -g @zereight/mcp-gitlab, ou npx -y @zereight/mcp-gitlab@latest).
|
|
56
|
+
Auth: GITLAB_PERSONAL_ACCESS_TOKEN e GITLAB_API_URL=https://gitlab.com/api/v4 (ou GITLAB_USE_OAUTH=true).
|
|
57
|
+
Local: claude mcp add gitlab --transport stdio --scope local --env GITLAB_PERSONAL_ACCESS_TOKEN="$GITLAB_PERSONAL_ACCESS_TOKEN" --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab
|
|
58
|
+
Ou: codex mcp add gitlab --env GITLAB_PERSONAL_ACCESS_TOKEN="$GITLAB_PERSONAL_ACCESS_TOKEN" --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab
|
|
59
|
+
Cursor: use o deeplink do README ou docs/clients/cursor.md.
|
|
60
|
+
HTTP remoto: aponte o cliente para https://mcp.example.com/mcp (Streamable HTTP). Claude.ai precisa de GITLAB_MCP_OAUTH nesse host.
|
|
61
|
+
Lista padrão: 40 ferramentas (38 core + discover_tools + help). Expanda com discover_tools. Não habilite o toolset api sem aceitar o risco de bypass.
|
|
62
|
+
Caminho equivalente sem MCP: npx skills add zereight/gitlab-mcp --skill gitlab-mcp-skill mais a CLI zereight-mcp-gitlab.
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
### HTTP remoto
|
|
66
|
+
|
|
67
|
+
Opção de primeira classe para servidor hospedado ou self-hosted. Aponte o cliente para uma URL Streamable HTTP:
|
|
68
|
+
|
|
69
|
+
```json
|
|
70
|
+
{
|
|
71
|
+
"mcpServers": {
|
|
72
|
+
"gitlab": {
|
|
73
|
+
"type": "http",
|
|
74
|
+
"url": "https://mcp.example.com/mcp"
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
- Hospedado / Claude.ai: `GITLAB_MCP_OAUTH=true` no servidor (veja [MCP OAuth](#usando-o-proxy-mcp-oauth-gitlab_mcp_oauth))
|
|
81
|
+
- Cabeçalhos PAT por usuário: `REMOTE_AUTHORIZATION=true` (veja [autorização remota](#usando-autorização-remota-remote_authorization))
|
|
82
|
+
- Exemplos Docker locais estão em [Uso](#uso)
|
|
83
|
+
|
|
84
|
+
### Skill + CLI (MCP não é obrigatório)
|
|
85
|
+
|
|
86
|
+
Skill + CLI é um caminho equivalente, não um fallback. Os mesmos fluxos, payload completo no terminal, sem registrar MCP.
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
npx skills add zereight/gitlab-mcp --skill gitlab-mcp-skill
|
|
90
|
+
zereight-mcp-gitlab user whoami
|
|
91
|
+
zereight-mcp-gitlab mr list
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Veja [CLI sem MCP](./docs/getting-started/cli-without-mcp.md) e [`skills/gitlab-mcp/`](./skills/gitlab-mcp/).
|
|
95
|
+
|
|
96
|
+
### MCP vs Human CLI
|
|
97
|
+
|
|
98
|
+
| Use o MCP quando | Use a CLI quando |
|
|
99
|
+
| ---------------- | ---------------- |
|
|
100
|
+
| O agente precisa de ferramentas estruturadas no chat | Você precisa do payload completo (diffs, logs, artefatos) |
|
|
101
|
+
| `jmespath` ou resultados compactos bastam | `GITLAB_MCP_COMPACT_RESULTS` está ligado e o resto vai para o terminal |
|
|
102
|
+
| Você já registrou o servidor | Você tem um PAT ou rodou `auth` e não quer MCP |
|
|
103
|
+
|
|
104
|
+
A CLI humana nunca é compactada. Ferramentas destrutivas e `GITLAB_TOOL_POLICY_APPROVE` precisam de `--yes`.
|
|
105
|
+
|
|
106
|
+
### Tips
|
|
107
|
+
|
|
108
|
+
`project_id` é um ID numérico ou um caminho com URL-encoding. Exemplo: grupo `group`, projeto `project`, merge request `!123` → `project_id=group%2Fproject`, `merge_request_iid=123`. Grupos aninhados usam `%2F` entre cada segmento (`group%2Fsubgroup%2Fproject`).
|
|
109
|
+
|
|
110
|
+
### FAQ
|
|
111
|
+
|
|
112
|
+
**Como autenticar?** No desktop local, `GITLAB_PERSONAL_ACCESS_TOKEN` (ou `GITLAB_PERSONAL_ACCESS_TOKEN_FILE`) é o mais simples. OAuth local é `GITLAB_USE_OAUTH=true`. Claude.ai remoto usa `GITLAB_MCP_OAUTH`. HTTP multi-usuário usa `REMOTE_AUTHORIZATION` e um cabeçalho de token por requisição.
|
|
113
|
+
|
|
114
|
+
**Por que vejo só ~40 ferramentas?** O toolset `core` padrão tem 38 ferramentas mais o `discover_tools` e o `help` sempre ligados. Chame `discover_tools` sem args para listar categorias e passe uma (`pipelines`, `wiki`, …) para ativá-la nesta sessão. `GITLAB_TOOLSETS=all` ainda **não** habilita `api`.
|
|
115
|
+
|
|
116
|
+
**OAuth local vs MCP OAuth vs auth remota?** OAuth local abre o navegador na mesma máquina do servidor. MCP OAuth é para um servidor HTTPS público e clientes como Claude.ai. Autorização remota encaminha o PAT ou job token do chamador; não há fluxo OAuth.
|
|
117
|
+
|
|
118
|
+
**Como encolher respostas enormes?** Passe `jmespath` em qualquer chamada. Ou defina `GITLAB_MCP_COMPACT_RESULTS=true` para trocar respostas MCP grandes por um preview e um comando CLI. Use a CLI quando quiser o payload completo.
|
|
119
|
+
|
|
120
|
+
**Por que o toolset `api` é perigoso?** `gitlab_api_request` ignora allowlists de grupo/projeto, outros filtros de ferramenta e checagens de segurança por ferramenta. Prompt injection pode acioná-lo. Habilite só listando `api` em `GITLAB_TOOLSETS`. `all`, `discover_tools` e `GITLAB_TOOLS` não fazem isso.
|
|
121
|
+
|
|
122
|
+
### Snippet de Cursor rule / CLAUDE.md
|
|
123
|
+
|
|
124
|
+
```
|
|
125
|
+
Merge requests, issues e pipelines do GitLab passam por este MCP (@zereight/mcp-gitlab).
|
|
126
|
+
Comece pelas ferramentas core padrão. Chame discover_tools para expandir.
|
|
127
|
+
Prefira list_merge_request_changed_files e depois get_merge_request_file_diff em lote.
|
|
128
|
+
Use jmespath ou resultados compactos; use a CLI para diffs e logs completos.
|
|
129
|
+
```
|
|
28
130
|
|
|
29
131
|
[](https://www.star-history.com/?repos=zereight%2Fgitlab-mcp&type=date&legend=top-left)
|
|
30
132
|
|
|
@@ -36,7 +138,7 @@ Suporta PAT, OAuth, modo somente leitura, URLs de API dinâmicas e autorização
|
|
|
36
138
|
|
|
37
139
|
### Por que usar este GitLab MCP?
|
|
38
140
|
|
|
39
|
-
- **
|
|
141
|
+
- **40 ferramentas por padrão (38 `core` + `discover_tools` + `help`); 278 no total** — comece enxuto; chame `discover_tools` para expandir nesta sessão
|
|
40
142
|
- **Revisão de MR em 2 etapas** — `list_merge_request_changed_files` → `get_merge_request_file_diff` em lote
|
|
41
143
|
- **Agent Skill integrado** — orientação de workflows em `skills/gitlab-mcp/`
|
|
42
144
|
- **Autenticação flexível** — Personal Access Token, fluxo OAuth2 local no navegador, proxy MCP OAuth e autorização remota por requisição
|
|
@@ -50,7 +152,7 @@ Suporta PAT, OAuth, modo somente leitura, URLs de API dinâmicas e autorização
|
|
|
50
152
|
| | @zereight/mcp-gitlab | GitLab MCP A (comunidade, estilo CQRS) | Servidor MCP oficial do GitLab |
|
|
51
153
|
| ------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
52
154
|
| **Mais indicado para** | Workflows de agentes de IA | Múltiplas instâncias corporativas / ferramentas agrupadas | Integrado ao GitLab, sem instalação separada |
|
|
53
|
-
| **Modelo de ferramentas** |
|
|
155
|
+
| **Modelo de ferramentas** | 278 ferramentas: 275 em toolsets + `execute_graphql` + `discover_tools` + `help` | ~50–60 ferramentas agrupadas `browse_*` / `manage_*` | Toolsets escolhidos por cabeçalho HTTP |
|
|
54
156
|
| **Revisão de MR** | Diff em lote em 2 etapas | Varia | `get_merge_request` com diffs |
|
|
55
157
|
| **Node.js** | >=18.17 | Frequentemente >=24 | Node.js 20+ para stdio via `mcp-remote` |
|
|
56
158
|
| **Licença** | MIT | Varia | Parte do GitLab |
|
|
@@ -603,7 +705,7 @@ Não é necessário definir `headers`. O Claude.ai obtém o token via OAuth.
|
|
|
603
705
|
|
|
604
706
|
## Arquivos de Agent Skill
|
|
605
707
|
|
|
606
|
-
Para agentes de IA que suportam carregamento de skills/instructions (Claude Code, GitHub Copilot, Cursor etc.), arquivos de skill pré-configurados estão disponíveis em [`skills/gitlab-mcp/`](./skills/gitlab-mcp/).
|
|
708
|
+
Skill + CLI é um caminho equivalente ao MCP (veja [Skill + CLI](#skill--cli-mcp-não-é-obrigatório)). Para agentes de IA que suportam carregamento de skills/instructions (Claude Code, GitHub Copilot, Cursor etc.), arquivos de skill pré-configurados estão disponíveis em [`skills/gitlab-mcp/`](./skills/gitlab-mcp/).
|
|
607
709
|
|
|
608
710
|
- **[SKILL.md](./skills/gitlab-mcp/SKILL.md)** — guia principal com visão geral dos toolsets, workflows importantes e dicas de parâmetros
|
|
609
711
|
- **[reference/](./skills/gitlab-mcp/reference/)** — documentação detalhada de workflows para code review, merge requests, issues, pipelines e triagem de vulnerabilidades
|