Troubleshooting

Solutions for common issues with GitLab MCP.

Quick Diagnosis

Symptom	Likely Cause	Guide
"Connection refused"	Server not running or wrong port	Connection
"401 Unauthorized"	Invalid or expired token	Connection
"403 Forbidden"	Insufficient token scopes	Connection
"No clients detected"	Client not installed or not detected	Clients
Server not appearing in client	Config file issue	Clients
Docker container won't start	Port conflict or missing env vars	Docker
Tools not available	Feature flags or read-only mode	Connection

General Steps

1. Check Configuration

Preview your current configuration:

npx @structured-world/gitlab-mcp install --show --claude-desktop

2. Test Connection

Verify your token and API access:

curl -H "PRIVATE-TOKEN: glpat-xxxx" \
  https://gitlab.com/api/v4/user

3. Check Logs

For Docker deployments:

gitlab-mcp docker logs -f

For stdio mode, check your MCP client's logs:

• Claude Desktop: ~/Library/Logs/Claude/mcp*.log (macOS)
• Cursor: Developer Tools (Cmd+Shift+I) > Console
• VS Code: Output panel > "MCP" channel

4. Verify Environment

Check which tools are available with current settings:

npx @structured-world/gitlab-mcp list-tools --env

Getting Help

If your issue isn't covered here:

1. Check the GitLab MCP GitHub Issues
2. Search existing issues for similar problems
3. Open a new issue with:
   • GitLab MCP version (npx @structured-world/gitlab-mcp --version)
   • Node.js version (node --version)
   • MCP client name and version
   • Error message or unexpected behavior
   • Minimal reproduction steps