GitLab MCP Server

A Model Context Protocol (MCP) server that connects Claude Code to GitLab's API, allowing you to interact with your GitLab repositories directly from Claude Code.

Features

• 📋 List and explore your GitLab projects
• 📊 View project details, branches, and merge requests
• 📄 Read file contents from repositories
• 🔍 All directly from Claude Code without switching to your browser

Installation

Prerequisites

This MCP server requires Python 3 and the requests module. Install the required Python package:

sudo apt-get install python3-requests

Quick Install (Recommended)

Install via your AI coding assistant CLI:

Claude Code

claude mcp add --scope user gitlab-mcp npx @davidfei/gitlab-mcp

You'll be prompted to enter your GitLab access token during setup.

Alternatively, you can provide the token directly:

claude mcp add --scope user gitlab-mcp --env GITLAB_TOKEN=your-token-here -- npx @davidfei/gitlab-mcp

Codex

Note: This MCP server requires Codex version 0.40.0 (not the latest version).

codex mcp add gitlab-mcp --env GITLAB_TOKEN=your-token-here -- npx @davidfei/gitlab-mcp

Gemini

gemini mcp add gitlab-mcp npx @davidfei/gitlab-mcp -t stdio -s user -e GITLAB_TOKEN=your-token-here

Get Your GitLab Personal Access Token

1. Go to GitLab.com (or your self-hosted GitLab instance)
2. Navigate to: User Settings → Access Tokens
3. Create a new token with at least these scopes:
   • api (full API access)
   • read_api (if you only need read operations)
   • read_repository (to read repository files)
4. Copy the token - you'll use it during installation

Available Tools

Once installed, Claude Code will have access to these GitLab tools:

1. list_projects

Lists all GitLab projects you're a member of.

Example: "Show me all my GitLab projects"

2. get_project

Retrieves detailed information about a specific project.

Parameters:

• project_id (required): The project ID or URL-encoded path

Example: "Get details for GitLab project ID 12345"

3. list_branches

Lists all branches in a repository.

Parameters:

• project_id (required): The project ID

Example: "Show me all branches in project 12345"

4. get_file

Retrieves the content of a file from a repository.

Parameters:

• project_id (required): The project ID
• file_path (required): Path to the file in the repository
• ref (optional): Branch/tag/commit (defaults to "main")

Examples:

• "Show me the README.md from project 12345"
• "Get the src/main.py file from the develop branch in project 12345"

5. list_merge_requests

Lists merge requests for a project.

Parameters:

• project_id (required): The project ID
• state (optional): Filter by state - "opened", "closed", "merged", or "all" (defaults to "opened")

Examples:

• "Show me open merge requests in project 12345"
• "List all merged MRs in project 12345"

Common Use Cases

Exploring a Repository

You: "List my GitLab projects"
Claude: [Lists projects with IDs]

You: "Get details for project 12345"
Claude: [Shows project info]

You: "List branches in project 12345"
Claude: [Shows all branches]

You: "Show me the README.md from project 12345"
Claude: [Displays file content]

Code Review Workflow

You: "Show me open merge requests in project 12345"
Claude: [Lists open MRs]

You: "Get the src/feature.py file from branch feature-xyz in project 12345"
Claude: [Shows the file content from that branch]

Multi-Project Analysis

You: "List all my GitLab projects, then for each one, check if there's a CHANGELOG.md file"
Claude: [Uses list_projects, then get_file for each project]

Troubleshooting

Authentication Issues

If you get 401 errors:

1. Verify your GITLAB_TOKEN is correct and not expired
2. Check that the token has the necessary scopes (api, read_api, read_repository)
3. Re-run the installation command with the correct token

Server Not Found

If the MCP server is not available:

1. Restart Claude Code
2. Verify the installation completed successfully
3. Check Claude Code logs for error messages

Project Not Found

If you get "project not found" errors:

1. Make sure you're using the correct project ID
2. Verify you have access to the project in GitLab
3. Try using the numeric project ID instead of the path

Self-Hosted GitLab

If you're using a self-hosted GitLab instance, you'll need to modify the server code to point to your instance. See DEVELOPMENT.md for details.

Tips

1. Get Project IDs First: Start by listing projects to get their IDs for other operations
2. Be Specific: Clearly specify what you want Claude to do
   • ✅ Good: "Show me the config.py file from the develop branch in project 12345"
   • ❌ Less good: "Look at my code"
3. Branch-Specific Work: Always specify the ref parameter when working with specific branches
4. Batch Operations: Ask Claude to perform operations across multiple projects or files
5. Combine Tools: Use GitLab MCP tools alongside Claude's code analysis capabilities

Security Notes

• Your GitLab token is sensitive - protect it like a password
• The token is stored in Claude Code's configuration
• Consider using a token with minimal required scopes
• Regularly rotate your GitLab tokens

Development & Contributing

For local development setup, testing, and contribution guidelines, see DEVELOPMENT.md.

For technical details about the MCP implementation, see CLAUDE.md.

License

MIT

Support

• Report issues at: GitLab Issues
• View source: GitLab Repository