에이전트 강화
게시자의 자체 명령입니다. PlugMCP 엔드포인트가 아닙니다.
Host a copy with our keys and logs.
npx -y [email protected]Claude Code에는 로컬 명령용 설치 링크가 없습니다. 아래 명령을 복사해 터미널에서 실행합니다.
claude mcp add mcpland-gitlab-mcp -- npx -y gitlab-mcp@1.7.0터미널에서 실행합니다.
{ "mcpServers": { "mcpland-gitlab-mcp": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}claude_desktop_config.json
원격 URL인가요, 내 컴퓨터에서 실행하는 명령인가요? 두 설치 방식의 차이
PlugMCP에서 실행
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
실행게시자 제공
A production-ready MCP server for GitLab. It lets AI assistants read and manage GitLab projects, merge requests, issues, pipelines, wikis, releases, and more through a broad, policy-controlled tool registry.
A MCP server for GitLab with powerful, safe, policy-controlled access
Claude Desktop, Claude Code, VS Code, GitHub Copilot Chat (VS Code), Cursor, JetBrains AI Assistant, GitLab Duo, and any MCP client that supports stdio or streamable HTTP.
Current client format references:
The server supports three auth patterns:
REMOTE_AUTHORIZATION=true, HTTP mode)Settings -> Applications.http://127.0.0.1:8765/callback (or your custom callback).api.GITLAB_OAUTH_CLIENT_ID.{
"mcpServers": {
"gitlab": {
"command": "npx",
"args": ["-y", "gitlab-mcp@latest"],
"env": {
"GITLAB_USE_OAUTH": "true",
"GITLAB_OAUTH_CLIENT_ID": "your_oauth_client_id",
"GITLAB_OAUTH_REDIRECT_URI": "http://127.0.0.1:8765/callback",
"GITLAB_API_URL": "https://gitlab.com/api/v4",
"GITLAB_ALLOWED_PROJECT_IDS": "",
"GITLAB_PERMISSION_MODE": "full",
"USE_GITLAB_WIKI": "true",
"USE_MILESTONE": "true",
"USE_PIPELINE": "true"
}
}
}
}
If your OAuth app is confidential, also set GITLAB_OAUTH_CLIENT_SECRET.
{
"mcpServers": {
"gitlab": {
"command": "npx",
"args": ["-y", "gitlab-mcp@latest"],
"env": {
"GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
"GITLAB_API_URL": "https://gitlab.com/api/v4",
"GITLAB_ALLOWED_PROJECT_IDS": "",
"GITLAB_PERMISSION_MODE": "full",
"USE_GITLAB_WIKI": "true",
"USE_MILESTONE": "true",
"USE_PIPELINE": "true"
}
}
}
}
.vscode/mcp.json examplesPAT with secure prompt input:
{
"inputs": [
{
"type": "promptString",
"id": "gitlab_token",
"description": "GitLab Personal Access Token",
"password": true
}
],
"servers": {
"gitlab": {
"type": "stdio",
"command": "node",
"args": ["/absolute/path/to/gitlab-mcp/dist/index.js"],
"env": {
"GITLAB_PERSONAL_ACCESS_TOKEN": "${input:gitlab_token}",
"GITLAB_API_URL": "https://gitlab.com/api/v4",
"GITLAB_PERMISSION_MODE": "full"
}
}
}
}
OAuth (confidential app) with secure prompt input:
{
"inputs": [
{
"type": "promptString",
"id": "gitlab_oauth_secret",
"description": "GitLab OAuth Client Secret",
"password": true
}
],
"servers": {
"gitlab": {
"type": "stdio",
"command": "node",
"args": ["/absolute/path/to/gitlab-mcp/dist/index.js"],
"env": {
"GITLAB_USE_OAUTH": "true",
"GITLAB_OAUTH_CLIENT_ID": "your_oauth_client_id",
"GITLAB_OAUTH_CLIENT_SECRET": "${input:gitlab_oauth_secret}",
"GITLAB_OAUTH_REDIRECT_URI": "http://127.0.0.1:8765/callback",
"GITLAB_API_URL": "https://gitlab.com/api/v4"
}
}
}
}
GitHub Copilot Chat in VS Code uses the same .vscode/mcp.json format.
Claude Desktop reads claude_desktop_config.json.
Claude Code supports project-level .mcp.json and claude mcp add-json.
Cursor uses .cursor/mcp.json.
{
"mcpServers": {
"gitlab": {
"command": "node",
"args": ["/absolute/path/to/gitlab-mcp/dist/index.js"],
"env": {
"GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
"GITLAB_API_URL": "https://gitlab.com/api/v4"
}
}
}
}
~/.gitlab/duo/mcp.json){
"mcpServers": {
"gitlab": {
"command": "node",
"args": ["/absolute/path/to/gitlab-mcp/dist/index.js"],
"env": {
"GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
"GITLAB_API_URL": "https://gitlab.com/api/v4"
}
}
},
"approvedTools": ["gitlab_get_project", "gitlab_list_merge_requests"]
}
JetBrains can import an existing MCP JSON config or register the server manually.
Use stdio command node /absolute/path/to/gitlab-mcp/dist/index.js, or HTTP endpoint http://127.0.0.1:3333/mcp with required headers.
Start server:
REMOTE_AUTHORIZATION=true \
HTTP_HOST=0.0.0.0 \
MCP_ALLOWED_HOSTS=127.0.0.1 \
HTTP_PORT=3333 \
node dist/http.js
Client config:
{
"mcpServers": {
"gitlab": {
"url": "http://127.0.0.1:3333/mcp",
"headers": {
"Authorization": "Bearer glpat-xxxxxxxxxxxxxxxxxxxx"
}
}
}
}
Dynamic per-request API URL:
REMOTE_AUTHORIZATION=true \
ENABLE_DYNAMIC_API_URL=true \
HTTP_HOST=0.0.0.0 \
MCP_ALLOWED_HOSTS=127.0.0.1 \
HTTP_PORT=3333 \
node dist/http.js
Add header in client requests:
{
"headers": {
"Authorization": "Bearer glpat-xxxxxxxxxxxxxxxxxxxx",
"X-GitLab-API-URL": "https://gitlab.example.com/api/v4"
}
}
Remote auth behavior matrix:
When HTTP_HOST is not 127.0.0.1, localhost, or ::1, HTTP startup rejects
server-side GITLAB_PERSONAL_ACCESS_TOKEN or GITLAB_JOB_TOKEN unless inbound
requests are protected by MCP_HTTP_AUTH_TOKEN, REMOTE_AUTHORIZATION=true, or
GITLAB_MCP_OAUTH=true.
For containerized deployments, PAT or remote auth is recommended.
OAuth interactive callback flow is usually less convenient in containers.
The Compose service listens on 0.0.0.0 inside the container but publishes only
127.0.0.1:3333 on the host by default. For the remote-authorization example,
set REMOTE_AUTHORIZATION=true in .env, leave server-side GitLab credentials
empty, and send each client's GitLab token as shown above.
docker compose up --build -d
or:
docker build -t gitlab-mcp .
docker run -d \
--name gitlab-mcp \
-p 127.0.0.1:3333:3333 \
-e HTTP_HOST=0.0.0.0 \
-e MCP_ALLOWED_HOSTS=127.0.0.1 \
-e REMOTE_AUTHORIZATION=true \
-e GITLAB_API_URL=https://gitlab.com/api/v4 \
gitlab-mcp
Clients must send their GitLab credential in Authorization: Bearer <token>,
Private-Token, or Job-Token. To keep a GitLab token in the container instead,
set a separate 32+ character MCP_HTTP_AUTH_TOKEN and require clients to send that
value as the bearer token; never expose a server-held GitLab token as the MCP bearer.
GITLAB_PROJECT_ID is not a supported environment variable in this repository.GITLAB_ALLOWED_PROJECT_IDS with one project ID, or pass project_id in tool arguments.--token or --api-url are not implemented (--env-file is supported).//).pnpm install
cp .env.example .env
pnpm build
# stdio (local MCP)
pnpm start
# streamable HTTP server (http://127.0.0.1:3333/mcp)
pnpm start:http
# optional: load a specific env file
pnpm start -- --env-file .env.local
pnpm start:http -- --env-file .env.local
SSE=true is not compatible with REMOTE_AUTHORIZATION=true.
Tools are organized into these categories. All GitLab tools use the gitlab_ prefix, except health_check.
See docs/tools.md for usage details and docs/tools-index.md for the generated complete registry.
The policy engine controls which tools are available at registration time:
# Read-only mode — exposes only read and GraphQL query capabilities
GITLAB_PERMISSION_MODE=readonly
# Modify mode — allows read/write/admin, but hides delete-capability tools
GITLAB_PERMISSION_MODE=modify
# Deprecated legacy kill switch; true takes precedence and forces readonly
GITLAB_READ_ONLY_MODE=true
# Disable specific capability classes without going fully read-only
GITLAB_DISABLED_CAPABILITIES=delete,graphql
# Only expose specific tools (supports with or without gitlab_ prefix)
GITLAB_ALLOWED_TOOLS=get_project,list_merge_requests,get_merge_request
# Or select compact domain presets (multiple values form a union)
GITLAB_TOOLSETS=core,wiki
# Opt in only for clients that still call legacy duplicate names
GITLAB_ENABLE_COMPATIBILITY_ALIASES=true
# Sensitive variable administration is hidden until explicitly enabled
GITLAB_ENABLE_CI_VARIABLE_TOOLS=true
# Optional second gate; callers must also pass include_value=true
GITLAB_ALLOW_CI_VARIABLE_VALUES=false
# Group Dependency Proxy administration is also opt-in
GITLAB_ENABLE_DEPENDENCY_PROXY_TOOLS=true
# Block tools by regex pattern
GITLAB_DENIED_TOOLS_REGEX=^gitlab_(delete|create)_
# Restrict to specific projects
GITLAB_ALLOWED_PROJECT_IDS=123,456,789
# Legacy compatibility setting; raw GraphQL remains disabled in project-scoped mode
GITLAB_ALLOW_GRAPHQL_WITH_PROJECT_SCOPE=false
# Disable feature groups
USE_PIPELINE=false
USE_GITLAB_WIKI=false
The two sensitive tool families use two independent gates. Enabling a family does not add it to the default core registry; select its toolset (or all) as well:
GITLAB_TOOLSETS=core,ci-variables,dependency-proxy
GITLAB_ENABLE_CI_VARIABLE_TOOLS=true
GITLAB_ENABLE_DEPENDENCY_PROXY_TOOLS=true
Unsafe or invalid GITLAB_DENIED_TOOLS_REGEX patterns fail startup.
In modify mode, raw GraphQL mutation tools remain available for updates, but the server parses each document and blocks mutation-root fields containing delete, destroy, remove, prune, or purge. Aliases and fragment expansion cannot bypass the check, and documents that cannot be verified fail closed.
GITLAB_ALLOWED_PROJECT_IDS is a strict resource boundary, not just a default project. Project-scoped tools validate every supplied source, target, and parent project ID. Safe global list/search tools return only allowed projects (global code search is executed once per allowed project), while group-wide, namespace-wide, user-wide, event-wide, fork, and unscoped create operations are hidden. Todo reads are filtered and a single todo is verified before mutation. Raw GraphQL executors are always hidden because an arbitrary document cannot be proven project-safe; project-bound Work Item tools remain available and enforce the same allowlist. The legacy GITLAB_ALLOW_GRAPHQL_WITH_PROJECT_SCOPE variable is retained for configuration compatibility but cannot override this boundary.
All configuration is done through environment variables. Key settings:
For file-based loading, .env is loaded by default. You can override it with:
node dist/index.js --env-file .env.local
node dist/http.js --env-file=.env.production
See docs/configuration.md for the complete reference.
Authentication behavior depends on mode:
REMOTE_AUTHORIZATION=true (HTTP strong mode)
Each request must include Authorization: Bearer <token>, Private-Token: <token>, or Job-Token: <token>.
When ENABLE_DYNAMIC_API_URL=true, each request must also include X-GitLab-API-URL.REMOTE_AUTHORIZATION=false (default mode)
The server resolves credentials in this order:
GITLAB_PERSONAL_ACCESS_TOKEN -> GITLAB_JOB_TOKEN -> OAuth PKCE (GITLAB_USE_OAUTH=true) -> GITLAB_TOKEN_SCRIPT -> GITLAB_TOKEN_FILE.Cookie-based auth (GITLAB_AUTH_COOKIE_PATH) is applied independently via a cookie jar and can work with or without a token.
See docs/authentication.md for setup guides.
pnpm dev # stdio mode with hot-reload
pnpm dev:http # HTTP mode with hot-reload
pnpm test # Run tests
pnpm test:live # Run opt-in read-only checks against a real GitLab instance
pnpm test:watch # Run tests in watch mode
pnpm lint # Lint
pnpm typecheck # Type check
pnpm inspector # Launch MCP Inspector
See docs/architecture.md for detailed design documentation.
This repository references and learns from parts of the implementation in zereight/gitlab-mcp. Thanks to the maintainers and contributors for their work.
MIT
A MCP server for GitLab with powerful, safe, policy-controlled access
{ "mcpServers": { "mcpland-gitlab-mcp": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}도구
아직 도구 목록이 없습니다. 원격 서버는 첫 상태 확인 후에 도구 목록이 생깁니다.
FAQ
이 페이지에서 Cursor, Claude Desktop, Claude Code 또는 VS Code용 stdio 설정을 복사합니다. PlugMCP 프록시가 아니라 게시자의 설치 방식을 사용합니다.
이 레코드에는 필수 환경 변수가 등록되어 있지 않습니다.
Gitlab은(는) stdio를 통해 로컬에서 실행됩니다.
마지막 확인: 2026-11-09. A MCP server for GitLab with powerful, safe, policy-controlled access