Claude Desktop Integration

Configure GitLab MCP for Claude Desktop.

Recommended: MCPB Extension

The easiest way to install — download and open the .mcpb bundle:

See MCPB installation guide for details.

Auto-Setup

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

Detection

Method	Details
Type	macOS app bundle
Bundle ID	com.anthropic.claudefordesktop
Auto-detected	Yes (when app is installed)

Config File Location

OS	Path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/claude/claude_desktop_config.json

Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@structured-world/gitlab-mcp"],
      "env": {
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
        "GITLAB_API_URL": "https://gitlab.com"
      }
    }
  }
}

Docker (stdio)

To run via Docker instead of npx:

{
  "mcpServers": {
    "gitlab": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "GITLAB_TOKEN",
        "-e", "GITLAB_API_URL",
        "ghcr.io/structured-world/gitlab-mcp:latest"
      ],
      "env": {
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
        "GITLAB_API_URL": "https://gitlab.com"
      }
    }
  }
}

Remote Server

Add a remote server through Customize > Connectors > Add custom connector, using its complete MCP endpoint, for example https://mcp.example.com/mcp. Complete OAuth when prompted.

Remote connectors run through Anthropic's cloud and cannot reach a server at your computer's localhost. Keep the local stdio configuration above for local access. See Anthropic's remote connector instructions and OAuth setup.

Verification

1. Open Claude Desktop
2. Check the MCP indicator (hammer icon) in the bottom-left
3. Click it to see connected servers
4. "gitlab" should appear with available tools listed

Troubleshooting

• Server not appearing: Restart Claude Desktop after config changes
• "Command not found": Ensure Node.js >= 24 is installed and npx is in PATH
• Connection errors: Check token scopes (api, read_user)
• Config file not found: Create the file and parent directories if they don't exist

See Also

• Quick Start
• Configuration reference
• Troubleshooting