Manual Configuration Guide

For users who prefer full control over their setup, you can configure GitLab MCP manually by editing your MCP client's configuration file directly.

Configuration Format

Configuration formats depend on the client. The JSON examples below use the mcpServers format accepted by Claude Desktop and Cursor. VS Code workspace configuration uses servers in .vscode/mcp.json; Codex manual registration uses TOML. Follow the corresponding client guide before copying an example.

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

Step-by-Step

1. Create a GitLab Token

Follow the Authentication Guide for detailed steps, or briefly:

1. Go to Settings > Access Tokens in your GitLab instance
2. Create a token with api and read_user scopes
3. Copy the token value

2. Find Your Config File

See Supported Clients for the config file location specific to your client and operating system.

3. Edit the Configuration

For the clients using the format above, add gitlab under mcpServers and preserve any existing entries. If the file does not exist, create the full structure. For VS Code, use its workspace configuration example, including the secure token input. For Codex, follow the Codex installation guide.

4. Set Environment Variables

Add any desired configuration options to the env object:

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@structured-world/gitlab-mcp"],
      "env": {
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
        "GITLAB_API_URL": "https://gitlab.company.com",
        "GITLAB_PROJECT_ID": "42",
        "GITLAB_READ_ONLY_MODE": "false",
        "USE_WORKITEMS": "true",
        "USE_PIPELINE": "true"
      }
    }
  }
}

5. Restart Your Client

After saving the config file, restart your MCP client to load the new configuration.

Alternative: Yarn dlx

If you prefer Yarn:

{
  "mcpServers": {
    "gitlab": {
      "command": "yarn",
      "args": ["dlx", "-q", "@structured-world/gitlab-mcp@latest", "stdio"],
      "env": {
        "GITLAB_TOKEN": "your_gitlab_token",
        "GITLAB_API_URL": "https://gitlab.com"
      }
    }
  }
}

Alternative: Docker (stdio)

For containerized execution:

{
  "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": "your_gitlab_token",
        "GITLAB_API_URL": "https://gitlab.com"
      }
    }
  }
}

Alternative: HTTP/SSE Remote Server

For connecting Claude Code to a running GitLab MCP server:

{
  "mcpServers": {
    "gitlab": {
      "type": "http",
      "url": "http://localhost:3333/mcp"
    }
  }
}

Other clients use different configuration formats. See the client guides.

Verifying Configuration

Use the install --show command to preview the generated configuration for any client:

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

Next Steps

• Environment Variables reference
• Feature Flags
• Transport Modes