GitLab MCP Server

GitLab MCP Server

A Model Context Protocol (MCP) server for GitLab integration with Claude Code and AI assistants.

Features

• Projects: List and get project details
• Branches: List and create branches
• Issues: Create and list issues
• Merge Requests: Create and list MRs
• Files: Read and write repository files
• Search: Search code in repositories

Requirements

• Bun >= 1.0 or Node.js >= 18
• GitLab Personal Access Token with api scope

Installation

The server is published on npm and can be run directly:

# Using Bun (recommended)
bunx @carmeloricarte/gitlab-mcp-server

# Using Node.js
npx @carmeloricarte/gitlab-mcp-server

No need to clone the repository or install dependencies manually.

Configuration

Set the following environment variables:

Variable	Required	Default	Description
GITLAB_TOKEN	Yes	-	GitLab Personal Access Token
GITLAB_HOST	No	https://gitlab.com	GitLab instance URL

For self-hosted GitLab with self-signed certificates:

export NODE_TLS_REJECT_UNAUTHORIZED=0

Environment Variables Setup

There are two approaches to configure credentials:

Option A: Variables in MCP Config (Simplest)

Pass all variables directly in the MCP configuration. Easiest for quick setup on new machines.

⚠️ Note: Token is stored in the config file (local, private). Acceptable for personal use.

Option B: System Environment Variables (More Secure)

Keep sensitive tokens at system/user level, only pass non-sensitive values in MCP config.

<details> <summary><strong>Windows (PowerShell)</strong></summary>

# Set permanently for current user
[Environment]::SetEnvironmentVariable("GITLAB_TOKEN", "glpat-your-token", "User")
[Environment]::SetEnvironmentVariable("GITLAB_HOST", "https://your-gitlab.com", "User")

# Verify
[Environment]::GetEnvironmentVariable("GITLAB_TOKEN", "User")

Restart your terminal/IDE after setting variables.

</details> <details> <summary><strong>macOS / Linux</strong></summary>

# Add to ~/.zshrc (macOS) or ~/.bashrc (Linux)
echo 'export GITLAB_TOKEN="glpat-your-token"' >> ~/.zshrc
echo 'export GITLAB_HOST="https://your-gitlab.com"' >> ~/.zshrc

# Reload
source ~/.zshrc

# Verify
echo $GITLAB_TOKEN

</details>

---

IDE / Tool Configuration

💡 Tip: Use bunx if you have Bun installed, or npx for Node.js. Both work identically.

⚠️ Important: ${VARIABLE} syntax does NOT work in most MCP configs - values are treated as literal strings, not resolved. Use Option A (hardcoded values) or Option B (system variables that the server reads from process.env).

⚠️ Windows Configuration

On Windows, you must wrap npx or bunx commands with cmd /c. Use this format:

{
  "command": "cmd",
  "args": ["/c", "npx", "-y", "@carmeloricarte/gitlab-mcp-server"]
}

Or with Bun:

{
  "command": "cmd",
  "args": ["/c", "bunx", "@carmeloricarte/gitlab-mcp-server"]
}

Important: The package name must always be the last argument in the args array.

---

Claude Code CLI

<details> <summary><strong>Option A: All variables in config</strong></summary>

claude mcp add-json GitLab '{
  "type": "stdio",
  "command": "bunx",
  "args": ["@carmeloricarte/gitlab-mcp-server"],
  "env": {
    "GITLAB_HOST": "https://your-gitlab.com",
    "GITLAB_TOKEN": "glpat-your-token",
    "NODE_TLS_REJECT_UNAUTHORIZED": "0"
  }
}'

</details> <details> <summary><strong>Option B: Token from system env</strong></summary>

Set GITLAB_TOKEN as system variable (see above), then:

claude mcp add-json GitLab '{
  "type": "stdio",
  "command": "bunx",
  "args": ["@carmeloricarte/gitlab-mcp-server"],
  "env": {
    "GITLAB_HOST": "https://your-gitlab.com",
    "NODE_TLS_REJECT_UNAUTHORIZED": "0"
  }
}'

</details>

Verify:

claude mcp list
# Expected: GitLab: bunx ... - ✓ Connected

---

VS Code (with MCP extension)

Edit ~/.vscode/mcp.json or .vscode/mcp.json in your project:

{
  "servers": {
    "GitLab": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@carmeloricarte/gitlab-mcp-server"],
      "env": {
        "GITLAB_HOST": "https://your-gitlab.com",
        "GITLAB_TOKEN": "glpat-your-token",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

---

Cursor

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "GitLab": {
      "command": "bunx",
      "args": ["@carmeloricarte/gitlab-mcp-server"],
      "env": {
        "GITLAB_HOST": "https://your-gitlab.com",
        "GITLAB_TOKEN"