GitLab MCP Server

@anupsahu/gitlab-mcp

MCP (Model Context Protocol) server for GitLab API with OAuth 2.0 PKCE authentication.

Features

• 🔐 OAuth 2.0 PKCE Authentication - Secure authentication with token persistence
• 🔄 Automatic Token Refresh - Seamless token renewal with retry logic
• 📁 Complete GitLab API Coverage - Merge requests, issues, files, commits, and more
• 💾 Token Persistence - Sessions survive server restarts
• 🛡️ Production Ready - Clean codebase with comprehensive error handling
• 🔧 Easy Configuration - Simple setup with environment variables

Installation

npm install -g @anupsahu/gitlab-mcp

Quick Start

1. OAuth Authentication (Recommended)

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@anupsahu/gitlab-mcp"],
      "env": {
        "USE_OAUTH": "true",
        "GITLAB_API_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}

2. Personal Access Token (Alternative)

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@anupsahu/gitlab-mcp"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "your_gitlab_token",
        "GITLAB_API_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}

OAuth Authentication

The server supports OAuth 2.0 PKCE authentication for secure access to GitLab:

1. Start the server with USE_OAUTH=true

2. Authenticate using the oauth_login_pkce tool

3. Tokens are automatically saved and persist across restarts

4. Port requirement: OAuth callback always uses http://localhost:7171 for compatibility with GitLab's official OAuth app. Ensure port 7171 is free during authentication.

5. Automatic token refresh handles expiration seamlessly

OAuth Tools

• oauth_login_pkce - Initiate OAuth authentication
• oauth_status - Check authentication status
• oauth_logout - Logout and clear tokens

Configuration

Environment Variables

| Variable | Description | Default | | ------------------------------- | -------------------------------------------- | --------------------------- | | USE_OAUTH | Enable OAuth 2.0 authentication | false | | GITLAB_API_URL | GitLab API URL | https://gitlab.com/api/v4 | | GITLAB_PERSONAL_ACCESS_TOKEN | Personal access token (if not using OAuth) | - | | GITLAB_PROJECT_ID | Default project ID | - | | GITLAB_ALLOWED_PROJECT_IDS | Comma-separated list of allowed project IDs | - | | GITLAB_READ_ONLY_MODE | Enable read-only mode | false | | OAUTH_REDIRECT_PORT_PREFERRED | Preferred localhost callback port | 7171 | | OAUTH_REDIRECT_PORT_RANGE | Fallback range for callback port (inclusive) | 7171-7199 |

Available Tools

Repository Operations

• search_repositories - Search for repositories
• get_repository_tree - Get repository file tree
• get_file_contents - Read file contents
• create_or_update_file - Create or update files
• push_files - Push multiple files

Merge Request Operations

• get_merge_request - Get merge request details
• get_merge_request_diffs - Get merge request changes
• create_merge_request - Create new merge request
• update_merge_request - Update merge request
• merge_merge_request - Merge a merge request

Issue Operations

• create_issue - Create new issue
• get_issue - Get issue details
• update_issue - Update issue
• list_issues - List issues

Commit Operations

• list_commits - List repository commits
• get_commit - Get commit details
• get_commit_diff - Get commit changes

Branch Operations

• create_branch - Create new branch
• fork_repository - Fork repository

Token Storage

OAuth tokens are automatically saved to:

• Path: ~/.config/gitlab-mcp/oauth-config.json
• Format: JSON configuration file
• Persistence: Tokens survive server restarts
• Security: Automatic token refresh and expiration handling

Examples

Authenticate with OAuth

// Use the oauth_login_pkce tool
{
  "sessionId": "my-session" // optional
}

Get Merge Request Details

{
  "project_id": "12345",
  "merge_request_iid": "123",
  "sessionId": "my-session"
}

Create Issue

{
  "project_id": "12345",
  "title": "Bug Report",
  "description": "Description of the issue",
  "sessionId": "my-session"
}

Development

# Clone repository
git clone https://gitlab.com/anupsahu/gitlab-mcp.git
cd gitlab-mcp

# Install dependencies
npm install

# Build
npm run build

# Run with OAuth
USE_OAUTH=true GITLAB_API_URL=https://gitlab.com/api/v4 node build/index.js

License

MIT License - see LICENSE file for details.

Contributing

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

Support

For issues and questions:

• Create an issue in the GitLab repository
• Check existing documentation and examples

Built with ❤️ for the MCP ecosystem