gitlab-mcp

sgaunet/gitlab-mcp

3.3

If you are the rightful owner of gitlab-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

GitLab MCP Server provides integration tools for GitLab within the Claude Code environment, leveraging the Model Context Protocol (MCP) for seamless interaction.

Tools
4
Resources
0
Prompts
0

GitHub release Go Report Card GitHub Downloads Coverage coverage Snapshot Build Release Build Vulnerability Scan

GitLab MCP Server

A Model Context Protocol (MCP) server that provides GitLab integration tools for Claude Code.

Features

  • List Issues: List issues for a GitLab project using project path (namespace/project-name)
  • Create Issues: Create new issues with title, description, labels, and assignees
  • Update Issues: Update existing issues (title, description, state, labels, assignees)
  • List Labels: List project labels with optional filtering and counts
  • Add Issue Notes: Add comments/notes to existing issues
  • Create Merge Requests: Create new merge requests with source/target branches, title, description, assignees, reviewers, and labels
  • Get Project Description: Retrieve the current description of a GitLab project
  • Update Project Description: Update the description of a GitLab project
  • Get Project Topics: Retrieve the current topics/tags of a GitLab project
  • Update Project Topics: Update the topics/tags of a GitLab project (replaces all existing topics)
  • Direct project path access - no need to resolve project IDs
  • Compatible with Claude Code's MCP architecture

Prerequisites

  • Go 1.21 or later
  • Task for build automation
  • Claude Code CLI
  • Access to GitLab repositories

Installation

Option 1: Install with Homebrew (Recommended for macOS/Linux)

# Add the tap and install
brew tap sgaunet/homebrew-tools
brew install sgaunet/tools/gitlab-mcp

Option 2: Download from GitHub Releases

  1. Download the latest release:

    Visit the releases page and download the appropriate binary for your platform:

    • macOS: gitlab-mcp_VERSION_darwin_amd64 (Intel) or gitlab-mcp_VERSION_darwin_arm64 (Apple Silicon)
    • Linux: gitlab-mcp_VERSION_linux_amd64 (x86_64) or gitlab-mcp_VERSION_linux_arm64 (ARM64)
    • Windows: gitlab-mcp_VERSION_windows_amd64.exe

  2. Make it executable (macOS/Linux):

    chmod +x gitlab-mcp_*

  3. Move to a location in your PATH:

    # Example for macOS/Linux
sudo mv gitlab-mcp_* /usr/local/bin/gitlab-mcp

Option 3: Build from Source

  1. Clone the repository:

    git clone https://github.com/sgaunet/gitlab-mcp.git
cd gitlab-mcp

  2. Build the project:

    task build

    Or manually:

    go build -o gitlab-mcp

  3. Install to your PATH:

    sudo mv gitlab-mcp /usr/local/bin/

Configuration

The MCP server requires a GitLab personal access token (PAT) with appropriate scopes (e.g., api, read_api, write_api) to interact with the GitLab API. Set the GITLAB_TOKEN environment variable with your PAT:

export GITLAB_TOKEN=your_personal_access_token

You can also set the GITLAB_URI environment variable if you're using a self-hosted GitLab instance (default is https://gitlab.com):

export GITLAB_URI=https://your.gitlab.instance

You can also configure label validation behavior with the GITLAB_VALIDATE_LABELS environment variable:

export GITLAB_VALIDATE_LABELS=true   # Default: Enable label validation
export GITLAB_VALIDATE_LABELS=false  # Disable label validation for backward compatibility

The easiest way to set these variables permanently is to add them to your shell profile (e.g., ~/.bashrc, ~/.zshrc). It avoids issues with environment variables not being available when Claude Code starts the MCP server.

Add to Claude Code

After installation, add the MCP server to Claude Code:

# If installed via Homebrew (Apple Silicon)
claude mcp add gitlab-mcp -s user -- /opt/homebrew/bin/gitlab-mcp

# If installed via Homebrew (Intel Mac) or manually to /usr/local/bin
claude mcp add gitlab-mcp -s user -- /usr/local/bin/gitlab-mcp

# If installed elsewhere, adjust the path accordingly
claude mcp add gitlab-mcp -s user -- /path/to/gitlab-mcp

Usage

Once installed, the MCP server provides the following tools in Claude Code:

list_issues

Lists issues for a GitLab project using the project path.

Parameters:

  • project_path (string, required): GitLab project path including all namespaces (e.g., 'namespace/project-name' or 'company/department/team/project'). Run 'git remote -v' to find the full path from the repository URL
  • state (string, optional): Filter by issue state (opened, closed, all) - defaults to opened
  • labels (string, optional): Comma-separated list of labels to filter by
  • limit (number, optional): Maximum number of issues to return (default: 100, max: 100)

Examples:

List all open issues for project namespace/project_name

List all issues (open and closed) for project namespace/project_name

List issues with state=all and limit=50 for project namespace/project_name

Response Format: Returns a JSON array of issue objects, each containing:

  • id: Issue ID
  • iid: Internal issue ID
  • title: Issue title
  • description: Issue description
  • state: Issue state (opened or closed)
  • labels: Array of label names
  • assignees: Array of assignee objects
  • created_at: Creation timestamp
  • updated_at: Last update timestamp

create_issues

Creates a new issue for a GitLab project.

Parameters:

  • project_path (string, required): GitLab project path including all namespaces (e.g., 'namespace/project-name' or 'company/department/team/project'). Run 'git remote -v' to find the full path from the repository URL
  • title (string, required): Issue title
  • description (string, optional): Issue description
  • labels (array, optional): Array of labels to assign to the issue
  • assignees (array, optional): Array of user IDs to assign to the issue

Examples:

Create an issue with title "Bug fix needed" for project namespace/project_name

Create an issue with title "Feature request", description "Add new functionality", and labels ["enhancement", "feature"] for project namespace/project_name

Label Validation: By default, the server validates that labels exist in the project before creating issues. If any labels don't exist, the issue creation fails with a helpful error message listing missing labels and all available labels in the project.

Example validation error:

The following labels do not exist in project 'namespace/project':
- 'nonexistent-label'
- 'typo-label'

Available labels in this project:
- bug, enhancement, documentation, priority-high, priority-medium, priority-low

To disable label validation, set GITLAB_VALIDATE_LABELS=false

To see available labels before creating issues, use the list_labels tool. Label validation can be disabled by setting GITLAB_VALIDATE_LABELS=false in your environment.

Response Format: Returns a JSON object of the created issue with the same structure as list_issues.

update_issues

Updates an existing issue for a GitLab project.

Parameters:

  • project_path (string, required): GitLab project path including all namespaces (e.g., 'namespace/project-name' or 'company/department/team/project'). Run 'git remote -v' to find the full path from the repository URL
  • issue_iid (number, required): Issue internal ID (IID) to update
  • title (string, optional): Updated issue title
  • description (string, optional): Updated issue description
  • state (string, optional): Issue state ('opened' or 'closed')
  • labels (array, optional): Array of labels to assign to the issue
  • assignees (array, optional): Array of user IDs to assign to the issue

Examples:

Update the title of issue #5 for project namespace/project_name

Close issue #10 and update its description for project namespace/project_name

Response Format: Returns a JSON object of the updated issue with the same structure as list_issues.

list_labels

Lists labels for a GitLab project with optional filtering.

Parameters:

  • project_path (string, required): GitLab project path including all namespaces (e.g., 'namespace/project-name' or 'company/department/team/project'). Run 'git remote -v' to find the full path from the repository URL
  • with_counts (boolean, optional): Include issue and merge request counts (default: false)
  • include_ancestor_groups (boolean, optional): Include labels from ancestor groups (default: false)
  • search (string, optional): Filter labels by search keyword
  • limit (number, optional): Maximum number of labels to return (default: 100, max: 100)

Examples:

List all labels for project namespace/project_name

List labels with counts for project namespace/project_name

Search for labels containing "bug" in project namespace/project_name

Response Format: Returns a JSON array of label objects, each containing:

  • id: Label ID
  • name: Label name
  • color: Label color (hex code)
  • text_color: Text color for the label
  • description: Label description
  • open_issues_count: Number of open issues (if with_counts=true)
  • closed_issues_count: Number of closed issues (if with_counts=true)
  • open_merge_requests_count: Number of open merge requests (if with_counts=true)

add_issue_note

Adds a note/comment to an existing issue for a GitLab project.

Parameters:

  • project_path (string, required): GitLab project path including all namespaces (e.g., 'namespace/project-name' or 'company/department/team/project'). Run 'git remote -v' to find the full path from the repository URL
  • issue_iid (number, required): Issue internal ID (IID) to add note to
  • body (string, required): Note/comment body text

Examples:

Add a comment "This looks good to me!" to issue #5 for project namespace/project_name

Add a note "Fixed in latest commit" to issue #12 for project namespace/project_name

Response Format: Returns a JSON object of the created note containing:

  • id: Note ID
  • body: Note body text
  • author: Author object with id, username, and name
  • created_at: Creation timestamp
  • updated_at: Last update timestamp
  • system: Boolean indicating if this is a system-generated note
  • noteable: Object containing information about the issue this note belongs to

create_merge_request

Creates a new merge request for a GitLab project.

Parameters:

  • project_path (string, required): GitLab project path including all namespaces (e.g., 'namespace/project-name' or 'company/department/team/project'). Run 'git remote -v' to find the full path from the repository URL
  • source_branch (string, required): Source branch name
  • target_branch (string, required): Target branch name
  • title (string, required): MR title
  • description (string, optional): MR description
  • assignee_ids (array, optional): Array of assignee user IDs
  • reviewer_ids (array, optional): Array of reviewer user IDs
  • labels (array, optional): Array of labels
  • milestone_id (number, optional): Milestone ID
  • remove_source_branch (boolean, optional): Auto-remove source branch after merge (default: true)
  • draft (boolean, optional): Create as draft MR (default: false)

Examples:

Create a merge request from feature-branch to main for project namespace/project_name

Create a merge request with assignees and labels from feature-branch to main for project namespace/project_name

Create a draft merge request with description "New feature implementation" from feature-branch to develop for project namespace/project_name

Response Format: Returns a JSON object of the created merge request containing:

  • id: Merge request ID
  • iid: Internal merge request ID
  • title: MR title
  • description: MR description
  • state: MR state (opened, closed, merged)
  • source_branch: Source branch name
  • target_branch: Target branch name
  • author: Author object with id, username, and name
  • assignees: Array of assignee objects
  • reviewers: Array of reviewer objects
  • labels: Array of label names
  • milestone: Milestone object (if assigned)
  • web_url: Web URL to the merge request
  • draft: Boolean indicating if this is a draft MR
  • created_at: Creation timestamp
  • updated_at: Last update timestamp

get_project_description

Retrieves the description of a GitLab project.

Parameters:

  • project_path (string, required): GitLab project path including all namespaces (e.g., 'namespace/project-name' or 'company/department/team/project'). Run 'git remote -v' to find the full path from the repository URL

Examples:

Get the project description for namespace/project_name

Response Format: Returns a JSON object containing:

  • id: Project ID
  • name: Project name
  • path: Project path
  • description: Project description

update_project_description

Updates the description of a GitLab project.

Parameters:

  • project_path (string, required): GitLab project path including all namespaces (e.g., 'namespace/project-name' or 'company/department/team/project'). Run 'git remote -v' to find the full path from the repository URL
  • description (string, required): The new description for the project

Examples:

Update the description of namespace/project_name to "A new and improved project description"

Response Format: Returns a JSON object containing:

  • id: Project ID
  • name: Project name
  • path: Project path
  • description: Updated project description
  • topics: Array of project topics

get_project_topics

Retrieves the topics/tags of a GitLab project.

Parameters:

  • project_path (string, required): GitLab project path including all namespaces (e.g., 'namespace/project-name' or 'company/department/team/project'). Run 'git remote -v' to find the full path from the repository URL

Examples:

Get the topics for namespace/project_name

Response Format: Returns a JSON object containing:

  • id: Project ID
  • name: Project name
  • path: Project path
  • topics: Array of topic strings

update_project_topics

Updates the topics/tags of a GitLab project (replaces all existing topics).

Parameters:

  • project_path (string, required): GitLab project path including all namespaces (e.g., 'namespace/project-name' or 'company/department/team/project'). Run 'git remote -v' to find the full path from the repository URL
  • topics (array, required): Array of topic strings to set for the project (replaces all existing topics)

Examples:

Update the topics of namespace/project_name to ["golang", "mcp", "gitlab", "api"]

Remove all topics from namespace/project_name by setting an empty array []

Response Format: Returns a JSON object containing:

  • id: Project ID
  • name: Project name
  • path: Project path
  • description: Project description
  • topics: Updated array of topic strings

Development

Build Tasks

This project uses Task for build automation. Available tasks:

# List all available tasks
task --list

# Build the binary
task build

# Build with coverage support
task build:coverage

# Run linter
task linter

# Run unit tests
task test

# Show test coverage percentage
task coverage

Running Tests

Unit Tests:

task test

Coverage Testing:

# Show coverage percentage
task coverage

The unit tests use interface abstractions and mocking to provide fast, reliable testing without external dependencies. Current test coverage is 78.8%.

Manual Testing

See for step-by-step manual testing instructions.

Automated Testing

Run the test script:

./test_working.sh

Configuration

The MCP server runs as a subprocess and communicates via JSON-RPC over stdin/stdout. Configuration is done through environment variables:

Environment Variables

  • GITLAB_TOKEN (required): GitLab personal access token with appropriate scopes (api, read_api, write_api)
  • GITLAB_URI (optional): GitLab instance URI (default: https://gitlab.com/)
  • GITLAB_VALIDATE_LABELS (optional): Enable/disable label validation for issue creation (default: true)
    • true: Validates that labels exist in the project before creating issues
    • false: Allows creating issues with non-existent labels (GitLab's default behavior)

MCP Transport Protocol

This server uses stdio (stdin/stdout) for communication, which is the standard and recommended approach for MCP servers:

✅ Why stdio is optimal:

  • Standard MCP pattern - Most MCP servers use stdio communication
  • Simple process model - Started by Claude Code as a subprocess
  • No port conflicts - No network port management needed
  • Security - Process isolation, no network exposure
  • Resource efficiency - Direct pipe communication with minimal overhead
  • Cross-platform compatibility - Works everywhere Go works
  • Easy configuration - Just specify the executable path in Claude Code

🌐 Alternative transports (HTTP/SSE): While MCP supports HTTP and Server-Sent Events, these are better suited for:

  • Multi-client scenarios (serving multiple agents simultaneously)
  • Containerized environments where process spawning is restricted
  • Remote access across network boundaries
  • Web-based MCP clients

For GitLab integration with Claude Code, stdio provides the best user experience with simple configuration and reliable performance.

Troubleshooting

Common Issues

  1. Parse Error (-32700): Ensure you're using the server through Claude Code's MCP interface, not directly inputting raw URLs
  2. Invalid URL: Verify the GitLab URL format is correct (SSH or HTTPS)
  3. Connection Issues: Check network connectivity to GitLab

Debug Mode

The server outputs debug information to stderr, which can be helpful for troubleshooting:

go run . < input.txt 2> debug.log

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

License

MIT License. See for details.

Support

For issues and questions, please create an issue in the repository.