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:

Start the server with USE_OAUTH=true
Authenticate using the oauth_login_pkce tool
Tokens are automatically saved and persist across restarts
Port requirement: OAuth callback always uses http://localhost:7171 for compatibility with GitLab's official OAuth app. Ensure port 7171 is free during authentication.
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

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
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

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Enables interaction with GitLab repositories through secure OAuth 2.0 authentication. Supports comprehensive GitLab operations including merge requests, issues, file management, commits, and branch operations through natural language.

Related MCP Servers

Github-Oauth MCP Server
Nikhil-Patil-RI
-
security
F
license
-
quality
Facilitates authentication with GitHub using OAuth protocol, allowing secure access and interaction with GitHub repositories and services.
Last updated -
4
GitHub MCP Server
tuanle96
A
security
F
license
A
quality
Enables comprehensive GitHub operations through natural language including file management, repository administration, issue tracking, and advanced code searching.
Last updated -
47
4
1
GitHub Enterprise MCP Server
piyushgIITian
-
security
A
license
-
quality
Enables interaction with GitHub repositories through the GitHub API, allowing file operations, repository management, issue tracking, and code search through natural language commands.
Last updated -
10
2
MIT License
GitLab MCP Server
lucky-dersan
-
security
F
license
-
quality
Provides GitLab integration for AI assistants using Model Context Protocol, enabling repository operations, file management, issue tracking, merge requests, and branch/tag administration through natural language.
Last updated -
2

View all related MCP servers

GitLab MCP Server