Hooking Up GitLab to Claude: A Beginner’s Guide to MCP

I spent an afternoon this week wiring up a GitLab MCP server so I could ask Claude things like “list my recent merge requests” and have it actually go look. It worked, and it’s genuinely changed how I navigate my company’s GitLab — but the setup process surfaced a few rough edges worth writing down for the next person.

This post is a step-by-step walkthrough of getting the GitLab MCP server running in Claude Code (the CLI) and Claude Desktop (the macOS app), aimed at people who haven’t touched MCP before.

What is MCP, briefly?

MCP stands for Model Context Protocol. It’s an open standard from Anthropic that lets AI assistants like Claude talk to external tools and services — your calendar, your email, your task tracker, your code host — through a uniform interface.

The mental model: an MCP server is a small program that exposes some capability (read GitLab issues, send a Slack message, query a database) as a set of “tools” Claude can call. Claude is the client. You configure the client to launch the server, and from then on Claude knows it has new powers.

For GitLab specifically, the community package @zereight/mcp-gitlab does the work — it speaks GitLab's REST API and exposes things like list_projects, get_merge_request, list_issues, and dozens more as MCP tools.

What you’ll need

• Node.js 18+ (so npx works)
• Claude Code and/or Claude Desktop installed
• A GitLab OAuth application registered against your GitLab instance, giving you a client ID and a redirect URI. Your platform team likely has one set up already — ask them for the values. If you’re doing this against gitlab.com for personal use, you can create one yourself under Preferences → Applications.

The OAuth flow is what lets the MCP server act on your behalf in GitLab without you pasting a personal access token into a config file.

Part 1: Claude Code (the CLI)

Claude Code ships with a claude mcp subcommand that handles the config for you. Use it. Editing ~/.claude.json by hand is possible but error-prone — I'll explain why in a moment.

Run this in your terminal, substituting your own OAuth client ID and GitLab API URL:

claude mcp add GitLab-MCP \
  -e GITLAB_USE_OAUTH=true \
  -e GITLAB_OAUTH_CLIENT_ID=<your-client-id> \
  -e GITLAB_OAUTH_REDIRECT_URI=http://127.0.0.1:8888/callback \
  -e GITLAB_API_URL=https://gitlab.com/api/v4 \
  -e GITLAB_READ_ONLY_MODE=false \
  -e USE_PIPELINE=true \
  -- npx -y @zereight/mcp-gitlab

A few notes on the flags:

• -e KEY=VALUE sets environment variables passed to the server process.
• The -- separates Claude's arguments from the command Claude should run.
• npx -y @zereight/mcp-gitlab downloads and launches the package on demand — no global install needed.
• GITLAB_READ_ONLY_MODE=false means Claude can do mutating things (open MRs, comment, etc.). Set it to true if you want a safer setup while you're getting comfortable.

Verify it’s registered and healthy:

claude mcp list
claude mcp get GitLab-MCP

You should see ✓ Connected. Then open Claude Code and run /mcp — it'll show every connected server and its tools.

The first time you ask Claude something that hits GitLab — “List my recent GitLab projects” — the OAuth flow will trigger. Your browser opens, you approve the app, GitLab redirects to 127.0.0.1:8888/callback, and you're authenticated. Subsequent calls just work.

Why not edit the config by hand?

I tried this first, and got bitten:

config['mcpServers']['GitLab-MCP'] = {...}
# KeyError: 'mcpServers'

If your ~/.claude.json has never had an MCP server before, the mcpServers key simply doesn't exist yet — you can't index into something that isn't there. The fix in Python is to use setdefault:

config.setdefault('mcpServers', {})['GitLab-MCP'] = {...}

But the bigger issue: Claude Code keeps ~/.claude.json open and may overwrite your edits when it exits. The claude mcp add command handles all of this safely. Use it.

Part 2: Claude Desktop

Claude Desktop doesn’t have an equivalent CLI helper, so here you do edit the config file directly — but carefully.

Quit Claude Desktop completely first (Cmd+Q, not just close the window). Otherwise it’ll overwrite your edits when it shuts down.

Back up the config:

cp ~/Library/Application\ Support/Claude/claude_desktop_config.json \
   ~/Library/Application\ Support/Claude/claude_desktop_config.json.bak

Then run this Python snippet, which adds the mcpServers key if it doesn't already exist:

python3 << 'EOF'
import json, os
path = os.path.expanduser('~/Library/Application Support/Claude/claude_desktop_config.json')
with open(path) as f:
    config = json.load(f)
config.setdefault('mcpServers', {})['GitLab-MCP'] = {
    "command": "npx",
    "args": ["-y", "@zereight/mcp-gitlab"],
    "env": {
        "GITLAB_USE_OAUTH": "true",
        "GITLAB_OAUTH_CLIENT_ID": "<your-client-id>",
        "GITLAB_OAUTH_REDIRECT_URI": "http://127.0.0.1:8888/callback",
        "GITLAB_API_URL": "https://gitlab.com/api/v4",
        "GITLAB_READ_ONLY_MODE": "false",
        "USE_PIPELINE": "true"
    }
}
with open(path, 'w') as f:
    json.dump(config, f, indent=2)
print("Done")
EOF

Note: unlike the Claude Code config, Claude Desktop doesn’t need a "type": "stdio" field — it's the default.

Validate the file is still valid JSON, then launch Claude Desktop:

python3 -m json.tool ~/Library/Application\ Support/Claude/claude_desktop_config.json

If it fails to connect, check the logs:

tail -f ~/Library/Logs/Claude/mcp*.log

The most common failure on macOS is PATH-related: GUI apps don’t inherit your shell’s PATH, so if you installed Node via nvm or Homebrew, Claude Desktop may not find npx. Fix it by replacing "command": "npx" with the absolute path from which npx (e.g., /opt/homebrew/bin/npx).

What you can actually do with it

Once connected, the experience is just… asking. A few prompts I’ve found useful:

• “List the merge requests assigned to me that are still open.”
• “Summarize the changes in MR !1234 in the infra/configs repo."
• “Find issues in the platform group labeled bug from the last week."
• “Show me my recent activity across all projects.”

The last one returned a clean table of every repo I’d pushed to, opened MRs in, or reviewed in the past month — exactly the kind of thing I’d normally hunt through GitLab’s UI for.

Wrapping up

MCP feels a bit like the early days of shell pipes: a small, composable protocol that turns isolated tools into something you can fluidly chain. Setting up one server is a 10-minute exercise; setting up five starts to feel like a personal toolbox.

If you hit the KeyError: 'mcpServers' issue I did, now you know — setdefault is your friend, but reach for the CLI command first whenever it exists.