GitLab MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@GitLab MCP Server list all open merge requests for the frontend-app project"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
GitLab MCP Server
A comprehensive Model Context Protocol (MCP) server that provides seamless GitLab API integration for Claude Desktop and other MCP clients. Manage your entire GitLab workflow through natural language commands - from project creation to repository operations, CI/CD management, and team collaboration.
🚀 Quick Start
# Install with uvx (recommended)
uvx --from gitlab-clone-mcp-server gitlab-mcp
# Or install as a tool
uv tool install gitlab-clone-mcp-serverRelated MCP server: GitLab MCP Server
🔌 Transport Options
GitLab MCP Server supports three transport types:
# Run with stdio transport (default)
gitlab-mcp stdio
# Run with SSE transport
gitlab-mcp sse --host localhost --port 8000
# Run with Streamable HTTP transport (recommended for production)
gitlab-mcp streamable-http --host localhost --port 8000See TRANSPORT_OPTIONS.md for detailed configuration.
✨ Key Features
Complete GitLab Integration: 46+ tools covering all major GitLab operations
Natural Language Interface: Control GitLab through conversational commands
Zero Configuration: Works out-of-the-box with your GitLab Personal Access Token
Comprehensive Coverage: Projects, repositories, issues, merge requests, CI/CD, and more
Local Repository Cloning: Clone repositories directly to your local machine
Batch Operations: Perform bulk operations across multiple projects
🛠️ Available Tools (46 Total)
📁 Project Management (12 tools)
Tool | Description |
| Create new GitLab projects with custom settings |
| Permanently delete GitLab projects |
| Modify project name, description, visibility |
| Fork projects to different namespaces |
| Archive projects for long-term storage |
| Restore archived projects |
| List all accessible projects with filters |
| Search projects by name or keywords |
| View project milestones and deadlines |
| List all project labels and colors |
| View configured webhooks |
| Get current user information and permissions |
📝 Issue Management (4 tools)
Tool | Description |
| List issues with state filtering |
| Create new issues with descriptions |
| Modify issue title, description, state |
| Close specific issues |
🔀 Merge Request Management (2 tools)
Tool | Description |
| List merge requests by state |
| Create new merge requests |
| Merge approved merge requests |
📄 File Operations (5 tools)
Tool | Description |
| Create new files with content |
| Modify existing file content |
| Remove files from repository |
| Read file contents |
| Browse directory structures |
🌿 Repository & Git Operations (15 tools)
Tool | Description |
| List all repository branches |
| Create new branches from any reference |
| Remove branches safely |
| View commit history |
| Create commits with multiple file changes |
| Compare differences between branches |
| Revert specific commits |
| Cherry-pick commits between branches |
| List all repository tags |
| Create release tags |
| Remove tags |
| Clone single repository locally |
| Batch clone all group repositories |
🚀 CI/CD Operations (3 tools)
Tool | Description |
| Monitor pipeline status |
| View individual job details |
| Start new pipeline runs |
👥 Groups & Collaboration (3 tools)
Tool | Description |
| List accessible GitLab groups |
| View group membership |
| Get user profile information |
Installation
Using uvx (Recommended)
uvx --from gitlab-clone-mcp-server gitlab-mcpUsing uv
uv tool install gitlab-mcp-serverFrom source
git clone <repository-url>
cd gitlab-mcp
uv syncSetup
Get GitLab Personal Access Token:
Go to GitLab → Settings → Access Tokens
Create token with
apiscopeCopy the token
Set environment variables:
export GITLAB_TOKEN="your_token_here" export GITLAB_URL="https://gitlab.com" # optionalTest the server:
gitlab-mcp
Configuration
Claude Desktop Configuration
Add to your Claude Desktop config (%APPDATA%\Claude\claude_desktop_config.json):
Using stdio transport (recommended)
{
"mcpServers": {
"gitlab": {
"command": "uvx",
"args": [
"--from", "gitlab-clone-mcp-server",
"gitlab-mcp", "stdio"
],
"env": {
"GITLAB_URL": "https://gitlab.com",
"GITLAB_TOKEN": "your_gitlab_token_here"
}
}
}
}Using HTTP transport
If you're running the server with Streamable HTTP transport:
{
"mcpServers": {
"gitlab": {
"url": "http://localhost:8000/mcp",
"headers": {
"GITLAB_TOKEN": "your_gitlab_token_here"
}
}
}
}Headers Integration
For applications using MCPToolset, connect with headers:
import os
from mcp_toolset import MCPToolset, SseServerParams
gitlab_tools = MCPToolset(
connection_params=SseServerParams(
url="http://localhost:8000/sse",
headers={"GITLAB_TOKEN": os.getenv("GITLAB_TOKEN")},
)
)💬 Usage Examples
Control GitLab through natural language commands:
Project Management:
"Create a new private project called 'microservice-api'"
"Fork the kubernetes/dashboard project to my namespace"
"Archive the old legacy-system project"
Issue & Code Review:
"Show all open issues in the backend-service project"
"Create merge request from feature/auth-system to main branch"
"Merge the approved MR #23 in mobile-app project"
Repository Operations:
"Create a new config.yaml file with database configuration"
"Show all branches in the web-application project"
"Clone the microservices-platform project to ./local-dev"
CI/CD & Teams:
"Show running pipelines for the deployment project"
"List all my GitLab groups and their members"
🔧 Authentication Setup
GitLab Personal Access Token
Go to GitLab → Settings → Access Tokens
Create token with these scopes:
✅
api- Full API access✅
read_repository- Read repository data✅
write_repository- Write repository data✅
read_user- Read user information
Copy the generated token
Environment Variables
Variable | Description | Default |
| Personal Access Token | Required |
| GitLab instance URL |
|
🔒 Security Best Practices
Never commit tokens to version control
Use environment variables for token storage
Set token expiration dates when possible
Rotate tokens regularly for enhanced security
Use minimal required scopes for your use case
🐛 Troubleshooting
Token Issues:
❌
GITLAB_TOKEN not set→ Set environment variable or provide in headers❌
401 Unauthorized→ Check token permissions and validity❌
403 Forbidden→ Verify project access permissions
Git Operations:
❌
Git command not found→ Install Git and add to PATH
Test Connection:
curl -H "PRIVATE-TOKEN: your_token" "https://gitlab.com/api/v4/user"🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
🔗 Related Projects
Made with ❤️ for the GitLab and MCP community
Available Tools
54 toolsarchive_projectB
Archive a project.
Args:
project_id: GitLab project ID
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: project_id (required), token, ctx. Returns: result
cherry_pick_commitC
Cherry-pick a commit.
Args:
project_id: GitLab project ID
commit_sha: Commit SHA to cherry-pick
branch: Target branch for cherry-pick
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: project_id (required), commit_sha (required), branch (required), token, +1 more. Returns: result
clone_group_repositoriesA
Clone all repositories from a GitLab group.
Args:
group_id: GitLab group ID
base_path: Base directory for cloned repos (default: ./repos)
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: group_id (required), base_path, token, ctx. Returns: result
clone_repositoryB
Clone a GitLab repository to local path.
Args:
project_id: GitLab project ID
local_path: Local directory path (optional, defaults to project name)
use_ssh: Use SSH URL instead of HTTPS (default: False)
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: project_id (required), local_path, use_ssh, token, +1 more. Returns: result
close_issueB
Close an issue.
Args:
project_id: GitLab project ID
issue_iid: Issue IID
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: project_id (required), issue_iid (required), token, ctx. Returns: result
compare_branchesC
Compare two branches.
Args:
project_id: GitLab project ID
from_branch: Source branch
to_branch: Target branch
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: project_id (required), from_branch (required), to_branch (required), token, +1 more. Returns: result
create_branchB
Create a new branch.
Args:
project_id: GitLab project ID
branch_name: New branch name
ref: Source branch/commit (default: main)
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: project_id (required), branch_name (required), ref, token, +1 more. Returns: result
create_commitA
Create a commit with file changes.
Args:
project_id: GitLab project ID
branch: Target branch
commit_message: Commit message
file_path: Path to the file
file_content: File content
action: Action (create, update, delete)
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: project_id (required), branch (required), commit_message (required), file_path (required), +4 more. Returns: result
create_fileC
Create a new file in repository.
Args:
project_id: GitLab project ID
file_path: Path for the new file
content: File content
branch: Target branch
commit_message: Commit message
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: project_id (required), file_path (required), content (required), branch (required), +3 more. Returns: result
create_issueB
Create a new issue in a GitLab project.
Args:
project_id: GitLab project ID
title: Issue title
description: Issue description (optional)
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: project_id (required), title (required), description, token, +1 more. Returns: result
create_merge_requestC
Create a merge request.
Args:
project_id: GitLab project ID
source_branch: Source branch
target_branch: Target branch
title: MR title
description: MR description (optional)
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: project_id (required), source_branch (required), target_branch (required), title (required), +3 more. Returns: result
create_projectB
Create a new GitLab project.
Args:
name: Project name
description: Project description (optional)
visibility: Project visibility (private, internal, public)
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: name (required), description, visibility, token, +1 more. Returns: result
create_tagC
Create a new tag.
Args:
project_id: GitLab project ID
tag_name: Tag name
ref: Source branch/commit
message: Tag message (optional)
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: project_id (required), tag_name (required), ref (required), message, +2 more. Returns: result
delete_branchC
Delete a branch.
Args:
project_id: GitLab project ID
branch_name: Branch name to delete
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: project_id (required), branch_name (required), token, ctx. Returns: result
delete_fileB
Delete a file from repository.
Args:
project_id: GitLab project ID
file_path: Path to the file
branch: Target branch
commit_message: Commit message
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: project_id (required), file_path (required), branch (required), commit_message (required), +2 more. Returns: result
delete_projectC
Delete a GitLab project.
Args:
project_id: GitLab project ID
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: project_id (required), token, ctx. Returns: result
delete_tagC
Delete a tag.
Args:
project_id: GitLab project ID
tag_name: Tag name to delete
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: project_id (required), tag_name (required), token, ctx. Returns: result
fork_projectA
Fork a project.
Args:
project_id: GitLab project ID to fork
namespace: Target namespace (optional)
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: project_id (required), namespace, token, ctx. Returns: result
get_commitsC
Get recent commits for a project.
Args:
project_id: GitLab project ID
ref_name: Branch name (default: main)
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: project_id (required), ref_name, token, ctx. Returns: result
get_current_userB
Get current user information.
Args:
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: token, ctx. Returns: result
get_file_contentA
Get content of a repository file.
Args:
project_id: GitLab project ID
file_path: Path to the file
ref: Branch/tag reference (default: main)
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: project_id (required), file_path (required), ref, token, +1 more. Returns: result
get_group_membersB
Get members of a GitLab group.
Args:
group_id: GitLab group ID
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: group_id (required), token, ctx. Returns: result
get_merge_requestsA
Get merge requests for a GitLab project.
Args:
project_id: GitLab project ID
state: MR state (opened, closed, merged, all)
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: project_id (required), state, token, ctx. Returns: result
get_pipeline_jobsC
Get jobs for a specific pipeline.
Args:
project_id: GitLab project ID
pipeline_id: Pipeline ID
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: project_id (required), pipeline_id (required), token, ctx. Returns: result
get_pipelinesA
Get CI/CD pipelines for a GitLab project.
Args:
project_id: GitLab project ID
status: Pipeline status (running, pending, success, failed, canceled, skipped)
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: project_id (required), status, token, ctx. Returns: result
get_projectB
Get detailed information about a specific project.
Args:
project_id: GitLab project ID
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: project_id (required), token, ctx. Returns: result
get_project_branchesB
Get branches for a GitLab project.
Args:
project_id: GitLab project ID
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: project_id (required), token, ctx. Returns: result
get_project_forksC
List forks of a project.
Args:
project_id: GitLab project ID
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: project_id (required), token, ctx. Returns: result
get_project_issuesB
Get issues for a GitLab project.
Args:
project_id: GitLab project ID
state: Issue state (opened, closed, all)
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: project_id (required), state, token, ctx. Returns: result
get_project_labelsC
Get project labels.
Args:
project_id: GitLab project ID
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: project_id (required), token, ctx. Returns: result
get_project_languagesB
Get programming languages used in a project.
Args:
project_id: GitLab project ID
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: project_id (required), token, ctx. Returns: result
get_project_milestonesB
Get project milestones.
Args:
project_id: GitLab project ID
state: Milestone state (active, closed, all)
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: project_id (required), state, token, ctx. Returns: result
get_project_usersB
Get users with access to a project.
Args:
project_id: GitLab project ID
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: project_id (required), token, ctx. Returns: result
get_repository_filesC
Get repository files and directories.
Args:
project_id: GitLab project ID
path: Directory path (optional)
ref: Branch/tag reference (default: main)
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: project_id (required), path, ref, token, +1 more. Returns: result
get_repository_tagsC
Get repository tags.
Args:
project_id: GitLab project ID
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: project_id (required), token, ctx. Returns: result
list_group_projectsB
List projects in a group by group name.
Args:
group_name: GitLab group name or path
per_page: Number of projects per page (max 100)
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: group_name (required), per_page, token, ctx. Returns: result
list_groupsA
List GitLab groups.
Args:
per_page: Number of groups per page (max 100)
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: per_page, token, ctx. Returns: result
list_project_hooksC
List project webhooks.
Args:
project_id: GitLab project ID
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: project_id (required), token, ctx. Returns: result
list_projectsA
List GitLab projects.
Args:
owned: If True, only show owned projects. If False, show all accessible projects.
per_page: Number of projects per page (max 100)
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: owned, per_page, token, ctx. Returns: result
list_starred_projectsB
List projects starred by a specific user.
Args:
user_id: GitLab user ID
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: user_id (required), token, ctx. Returns: result
list_user_projectsC
List projects owned by a specific user.
Args:
user_id: GitLab user ID
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: user_id (required), token, ctx. Returns: result
merge_merge_requestB
Merge a merge request.
Args:
project_id: GitLab project ID
merge_request_iid: Merge request IID
merge_commit_message: Custom merge commit message (optional)
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: project_id (required), merge_request_iid (required), merge_commit_message, token, +1 more. Returns: result
revert_commitB
Revert a commit.
Args:
project_id: GitLab project ID
commit_sha: Commit SHA to revert
branch: Target branch for revert
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: project_id (required), commit_sha (required), branch (required), token, +1 more. Returns: result
search_projectsC
Search for projects.
Args:
query: Search query
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: query (required), token, ctx. Returns: result
star_projectB
Star a project.
Args:
project_id: GitLab project ID
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: project_id (required), token, ctx. Returns: result
transfer_projectB
Transfer a project to a new namespace.
Args:
project_id: GitLab project ID
namespace: Target namespace (user or group)
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: project_id (required), namespace (required), token, ctx. Returns: result
trigger_pipelineA
Trigger a new pipeline.
Args:
project_id: GitLab project ID
ref: Branch/tag to run pipeline on (default: main)
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: project_id (required), ref, token, ctx. Returns: result
unarchive_projectC
Unarchive a project.
Args:
project_id: GitLab project ID
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: project_id (required), token, ctx. Returns: result
unstar_projectA
Unstar a project.
Args:
project_id: GitLab project ID
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: project_id (required), token, ctx. Returns: result
update_fileB
Update an existing file in repository.
Args:
project_id: GitLab project ID
file_path: Path to the file
content: New file content
branch: Target branch
commit_message: Commit message
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: project_id (required), file_path (required), content (required), branch (required), +3 more. Returns: result
update_issueA
Update an issue.
Args:
project_id: GitLab project ID
issue_iid: Issue IID
title: New title (optional)
description: New description (optional)
state_event: State change (close, reopen) (optional)
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: project_id (required), issue_iid (required), title, description, +3 more. Returns: result
update_projectB
Update project settings.
Args:
project_id: GitLab project ID
name: New project name (optional)
description: New description (optional)
visibility: New visibility (private, internal, public) (optional)
token: GitLab Personal Access Token (optional)
ctx: MCP context (automatically injected)
Inputs: project_id (required), name, description, visibility, +2 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 54 tools
Most tools have clearly distinct purposes, but there is some overlap: create_commit can also create/update/delete files, making it redundant with create_file, update_file, and delete_file. Additionally, close_issue duplicates functionality available via update_issue with state_event. These overlaps could cause misselection, though descriptions help clarify.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., archive_project, get_project_issues, create_merge_request). The only slight redundancy is 'merge_merge_request', but it still adheres to the pattern. Naming is predictable and clear.
With 54 tools, the server covers a wide range of GitLab operations but feels heavy. Several tools are niche (e.g., list_starred_projects, clone_group_repositories) or redundant, suggesting the set could be trimmed. A count of 20-30 would be more appropriate for the scope.
Core CRUD operations for projects, issues, branches, tags, files, merge requests, and pipelines are present. However, notable gaps exist: no way to comment on issues or merge requests, no update/close for merge requests, and no creation of project hooks. These missing features limit agent workflows.
Maintenance
Related MCP Connectors
AI-native git hosting — repos, PRs, issues, CI gates, and AI code review over MCP (60 tools).
Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language.
Plain-English git for agents: 22 tools to branch, commit, push and tag. Free tier.
Git-backed platform for skills, tools, and context for AI agents
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables comprehensive GitLab integration allowing LLMs to manage projects, issues, merge requests, repository files, CI/CD pipelines, and perform batch operations. Supports advanced features like AI-optimized summaries, smart diffs, and atomic operations with rollback support.723Apache 2.0
- AlicenseNot gradedqualityDmaintenanceEnables 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.18 npmMIT
- FlicenseNot gradedqualityDmaintenanceEnables interaction with GitLab repositories through natural language, supporting project management, issue tracking, merge requests, file access, and repository operations. Includes a conversational agent interface with structured outputs for comprehensive GitLab workflow automation.-
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to interact with GitLab repositories, manage merge requests, review code diffs, post comments, and handle issues directly through natural language.125 npmMIT