Quick Configuration
Choose the setup that matches your environment.
Before You Start
- Confirm you have the account, endpoint, or API key required for GitLab.
- Start with minimum scopes and read-only access where possible.
- Keep secrets in environment variables instead of hardcoding them in JSON.
Last verified: 2026-06-13
Environment: Node.js 18+, @zereight/mcp-gitlab over stdio (the official reference server is deprecated)
Install command:
npx -y @zereight/mcp-gitlabLocal config
JSON Local config json
{
"gitlab": {
"command": "npx",
"args": ["-y", "@zereight/mcp-gitlab"],
"env": {
"GITLAB_PERSONAL_ACCESS_TOKEN": "${GITLAB_PERSONAL_ACCESS_TOKEN}",
"GITLAB_API_URL": "https://gitlab.com/api/v4",
"GITLAB_READ_ONLY_MODE": "true"
}
}
}After copying
Check the GitLab JSON before running it in OpenClaw, then verify the server with a real prompt.
Verify prompt
List my GitLab projects and summarize the open issues assigned to me.
Expected success output
You should see your projects and assigned issues returned read-only.
Common Pitfalls & Fixes
- ⚠️ Watch out: Personal access token scopes, self-managed base URL, and group/project IDs.
- 🔑 Always store API keys in environment variables, never hardcode them in JSON.
- 🛡️ Start with read-only scopes if available to verify connection safely.
Security checklist
- Use a least-scope PAT (read_api) and keep GITLAB_READ_ONLY_MODE=true by default.
- The official @modelcontextprotocol/server-gitlab is deprecated; this guide uses the maintained @zereight/mcp-gitlab.
Common errors
| Error | Cause | Fix |
|---|---|---|
401 Unauthorized | The token is missing or invalid. | Create a PAT with read_api scope and set GITLAB_PERSONAL_ACCESS_TOKEN. |
404 / project not found | GITLAB_API_URL is wrong for a self-managed instance. | Point GITLAB_API_URL at your instance's /api/v4 endpoint. |
Write blocked | GITLAB_READ_ONLY_MODE=true blocks mutations by design. | Set it to false only when you intend to write. |
Example Prompts
Once connected, try these prompts to test capabilities:
- List open merge requests in my project and summarize what each changes.
- Find issues labeled "bug" updated in the last 7 days and group by status.
- Show the latest pipeline status and highlight any failing jobs.
Verification Checklist
- Run 1-2 real prompts to confirm GitLab returns usable data.
- Check that error messages are clear enough for troubleshooting.
- Document the required scopes, dependencies, and env vars for future reuse.