✨ From vibe coding to vibe deployment. UBOS MCP turns ideas into infra with one message.

Learn more

GitLab MCP Server

GitLab MCP Server Logo

npm License: MIT GitHub issues GitHub stars

A powerful Model Context Protocol (MCP) server for GitLab integration, enabling AI assistants to interact with your GitLab resources.

✨ Features

  • Comprehensive GitLab API Integration - Access repositories, issues, merge requests, wikis, and more
  • Both Transports Supported - Use with stdio or Server-Sent Events (SSE)
  • Consistent Response Formatting - Standardized pagination and response structures
  • Strong TypeScript Typing - Built with the MCP SDK for type safety
  • Complete Documentation - Examples for all available tools

🔍 Supported Operations

  • Repository Management - Search, create, fork repositories
  • File Handling - Read, create, update files
  • Branch Operations - Create and manage branches
  • Issue Tracking - Create, list, filter issues
  • Merge Requests - Create, list, review merge requests
  • Group Management - List group projects and members
  • Project Activity - Track events and commit history
  • Wiki Management - Full support for project and group wikis with attachments
  • Member Management - List and manage project/group members

🚀 Getting Started

Installation

From npm (Recommended)

npm install @yoda.digital/gitlab-mcp-server

From Source

# Clone the repository
git clone https://github.com/yoda-digital/mcp-gitlab-server.git
cd mcp-gitlab-server

# Install dependencies
npm install

# Build the project
npm run build

Configuration

Environment Variables

The server requires the following environment variables:

VariableRequiredDefaultDescription
GITLAB_PERSONAL_ACCESS_TOKENYes-Your GitLab personal access token
GITLAB_API_URLNohttps://gitlab.com/api/v4GitLab API URL
PORTNo3000Port for SSE transport
USE_SSENofalseSet to ‘true’ to use SSE transport
GITLAB_READ_ONLY_MODENofalseSet to ‘true’ to enable read-only mode (see below)

Read-Only Mode

When GITLAB_READ_ONLY_MODE is set to true, the server will only expose read operations. This is useful for client applications that shouldn’t have write access to your GitLab resources. In read-only mode, the following tools will be available:

  • search_repositories
  • get_file_contents
  • list_group_projects
  • get_project_events
  • list_commits
  • list_issues
  • list_merge_requests
  • list_project_wiki_pages
  • get_project_wiki_page
  • list_group_wiki_pages
  • get_group_wiki_page
  • list_project_members
  • list_group_members

Any attempt to use write operations (create, update, delete) will result in an error when in read-only mode.

MCP Settings Configuration

Add the GitLab MCP server to your MCP settings file:

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@yoda.digital/gitlab-mcp-server"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "your_token_here",
        "GITLAB_API_URL": "https://gitlab.com/api/v4"
      },
      "alwaysAllow": [],
      "disabled": false
    }
  }
}

For read-only mode, add the GITLAB_READ_ONLY_MODE environment variable:

{
  "mcpServers": {
    "gitlab-readonly": {
      "command": "npx",
      "args": ["-y", "@yoda.digital/gitlab-mcp-server"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "your_token_here",
        "GITLAB_API_URL": "https://gitlab.com/api/v4",
        "GITLAB_READ_ONLY_MODE": "true"
      },
      "alwaysAllow": [],
      "disabled": false
    }
  }
}

Usage

With stdio transport (default)

# Set your GitLab personal access token
export GITLAB_PERSONAL_ACCESS_TOKEN=your_token_here

# Run the server
npm start

With SSE transport

# Set your GitLab personal access token and enable SSE
export GITLAB_PERSONAL_ACCESS_TOKEN=your_token_here
export GITLAB_READ_ONLY_MODE=false
export USE_SSE=true
export PORT=3000  # Optional, defaults to 3000

# Run the server
npm start

With npx

# Run directly with npx
GITLAB_PERSONAL_ACCESS_TOKEN=your_token_here npx @yoda.digital/gitlab-mcp-server

🛠️ Available Tools

Repository Operations

search_repositories: Search for GitLab projects
{
  "search": "project-name",
  "page": 1,
  "per_page": 20
}
create_repository: Create a new GitLab project
{
  "name": "new-project",
  "description": "A new project",
  "visibility": "private",
  "initialize_with_readme": true
}
fork_repository: Fork a GitLab project
{
  "project_id": "username/project",
  "namespace": "target-namespace"
}
list_group_projects: List all projects within a specific GitLab group
{
  "group_id": "group-name",
  "archived": false,
  "visibility": "public",
  "include_subgroups": true,
  "page": 1,
  "per_page": 20
}

File Operations

get_file_contents: Get the contents of a file from a GitLab project
{
  "project_id": "username/project",
  "file_path": "path/to/file.txt",
  "ref": "main"
}
create_or_update_file: Create or update a single file in a GitLab project
{
  "project_id": "username/project",
  "file_path": "path/to/file.txt",
  "content": "File content here",
  "commit_message": "Add/update file",
  "branch": "main",
  "previous_path": "old/path/to/file.txt"
}
push_files: Push multiple files to a GitLab project in a single commit
{
  "project_id": "username/project",
  "files": [
    {
      "path": "file1.txt",
      "content": "Content for file 1"
    },
    {
      "path": "file2.txt",
      "content": "Content for file 2"
    }
  ],
  "commit_message": "Add multiple files",
  "branch": "main"
}

Branch Operations

create_branch: Create a new branch in a GitLab project
{
  "project_id": "username/project",
  "branch": "new-branch",
  "ref": "main"
}

Issue Operations

create_issue: Create a new issue in a GitLab project
{
  "project_id": "username/project",
  "title": "Issue title",
  "description": "Issue description",
  "assignee_ids": [1, 2],
  "milestone_id": 1,
  "labels": ["bug", "critical"]
}
list_issues: Get issues for a GitLab project with filtering
{
  "project_id": "username/project",
  "state": "opened",
  "labels": "bug,critical",
  "milestone": "v1.0",
  "author_id": 1,
  "assignee_id": 2,
  "search": "keyword",
  "created_after": "2023-01-01T00:00:00Z",
  "created_before": "2023-12-31T23:59:59Z",
  "updated_after": "2023-06-01T00:00:00Z",
  "updated_before": "2023-06-30T23:59:59Z",
  "page": 1,
  "per_page": 20
}
list_issue_notes: Get all comments and system notes for a GitLab issue
{
  "project_id": "username/project",
  "issue_iid": 42,
  "sort": "desc",
  "order_by": "created_at",
  "page": 1,
  "per_page": 20
}

Response Format:

{
  "count": 15,
  "notes": [
    {
      "id": 123456,
      "body": "This is a comment on the issue",
      "author": {
        "id": 1,
        "username": "username",
        "name": "User Name"
      },
      "created_at": "2023-01-01T00:00:00Z",
      "updated_at": "2023-01-01T00:00:00Z",
      "system": false,
      "type": "comment"
    },
    {
      "id": 123457,
      "body": "added label ~bug",
      "author": {
        "id": 1,
        "username": "username",
        "name": "User Name"
      },
      "created_at": "2023-01-02T00:00:00Z",
      "updated_at": "2023-01-02T00:00:00Z",
      "system": true,
      "type": "system"
    }
    // ... other notes
  ]
}
list_issue_discussions: Get all discussions (threaded comments) for a GitLab issue
{
  "project_id": "username/project",
  "issue_iid": 42,
  "page": 1,
  "per_page": 20
}

Response Format:

{
  "count": 5,
  "discussions": [
    {
      "id": "discussion-123",
      "individual_note": true,
      "notes": [
        {
          "id": 123456,
          "body": "This is a comment on the issue",
          "author": {
            "id": 1,
            "username": "username",
            "name": "User Name"
          },
          "created_at": "2023-01-01T00:00:00Z",
          "updated_at": "2023-01-01T00:00:00Z",
          "system": false,
          "type": "comment"
        }
      ]
    },
    {
      "id": "discussion-124",
      "individual_note": false,
      "notes": [
        {
          "id": 123457,
          "body": "This is a thread starter",
          "author": {
            "id": 1,
            "username": "username",
            "name": "User Name"
          },
          "created_at": "2023-01-02T00:00:00Z",
          "updated_at": "2023-01-02T00:00:00Z",
          "system": false,
          "type": "comment"
        },
        {
          "id": 123458,
          "body": "This is a reply in the thread",
          "author": {
            "id": 2,
            "username": "username2",
            "name": "User Name 2"
          },
          "created_at": "2023-01-03T00:00:00Z",
          "updated_at": "2023-01-03T00:00:00Z",
          "system": false,
          "type": "comment"
        }
      ]
    }
    // ... other discussions
  ]
}

Merge Request Operations

create_merge_request: Create a new merge request in a GitLab project
{
  "project_id": "username/project",
  "title": "Merge request title",
  "description": "Merge request description",
  "source_branch": "feature-branch",
  "target_branch": "main",
  "allow_collaboration": true,
  "draft": false
}
list_merge_requests: Get merge requests for a GitLab project with filtering
{
  "project_id": "username/project",
  "state": "opened",
  "order_by": "created_at",
  "sort": "desc",
  "milestone": "v1.0",
  "labels": "feature,enhancement",
  "created_after": "2023-01-01T00:00:00Z",
  "created_before": "2023-12-31T23:59:59Z",
  "updated_after": "2023-06-01T00:00:00Z",
  "updated_before": "2023-06-30T23:59:59Z",
  "author_id": 1,
  "assignee_id": 2,
  "search": "keyword",
  "source_branch": "feature-branch",
  "target_branch": "main",
  "page": 1,
  "per_page": 20
}

Project Activity

get_project_events: Get recent events/activities for a GitLab project
{
  "project_id": "username/project",
  "action": "pushed",
  "target_type": "issue",
  "before": "2023-12-31T23:59:59Z",
  "after": "2023-01-01T00:00:00Z",
  "sort": "desc",
  "page": 1,
  "per_page": 20
}
list_commits: Get commit history for a GitLab project
{
  "project_id": "username/project",
  "sha": "branch-or-commit-sha",
  "path": "path/to/file",
  "since": "2023-01-01T00:00:00Z",
  "until": "2023-12-31T23:59:59Z",
  "all": true,
  "with_stats": true,
  "first_parent": true,
  "page": 1,
  "per_page": 20
}

Member Operations

list_project_members: List all members of a GitLab project (including inherited members)
{
  "project_id": "username/project",
  "query": "search term",
  "page": 1,
  "per_page": 20
}

Response Format:

{
  "count": 3,
  "items": [
    {
      "id": 123,
      "username": "username",
      "name": "User Name",
      "state": "active",
      "avatar_url": "https://gitlab.com/avatar.png",
      "web_url": "https://gitlab.com/username",
      "access_level": 50,
      "access_level_description": "Owner"
    }
    // ... other members
  ]
}
list_group_members: List all members of a GitLab group (including inherited members)
{
  "group_id": "group-name",
  "query": "search term",
  "page": 1,
  "per_page": 20
}

Response Format:

{
  "count": 5,
  "items": [
    {
      "id": 456,
      "username": "username",
      "name": "User Name",
      "state": "active",
      "avatar_url": "https://gitlab.com/avatar.png",
      "web_url": "https://gitlab.com/username",
      "access_level": 30,
      "access_level_description": "Developer"
    }
    // ... other members
  ]
}

Project Wiki Operations

list_project_wiki_pages: List all wiki pages for a GitLab project
{
  "project_id": "username/project",
  "with_content": false
}
get_project_wiki_page: Get a specific wiki page for a GitLab project
{
  "project_id": "username/project",
  "slug": "page-slug",
  "render_html": false,
  "version": "commit-sha"
}
create_project_wiki_page: Create a new wiki page for a GitLab project
{
  "project_id": "username/project",
  "title": "Page Title",
  "content": "Wiki page content",
  "format": "markdown"
}
edit_project_wiki_page: Edit an existing wiki page for a GitLab project
{
  "project_id": "username/project",
  "slug": "page-slug",
  "title": "New Page Title",
  "content": "Updated wiki page content",
  "format": "markdown"
}
delete_project_wiki_page: Delete a wiki page from a GitLab project
{
  "project_id": "username/project",
  "slug": "page-slug"
}
upload_project_wiki_attachment: Upload an attachment to a GitLab project wiki
{
  "project_id": "username/project",
  "file_path": "path/to/attachment.png",
  "content": "base64-encoded-content",
  "branch": "main"
}

Group Wiki Operations

list_group_wiki_pages: List all wiki pages for a GitLab group
{
  "group_id": "group-name",
  "with_content": false
}
get_group_wiki_page: Get a specific wiki page for a GitLab group
{
  "group_id": "group-name",
  "slug": "page-slug",
  "render_html": false,
  "version": "commit-sha"
}
create_group_wiki_page: Create a new wiki page for a GitLab group
{
  "group_id": "group-name",
  "title": "Page Title",
  "content": "Wiki page content",
  "format": "markdown"
}
edit_group_wiki_page: Edit an existing wiki page for a GitLab group
{
  "group_id": "group-name",
  "slug": "page-slug",
  "title": "New Page Title",
  "content": "Updated wiki page content",
  "format": "markdown"
}
delete_group_wiki_page: Delete a wiki page from a GitLab group
{
  "group_id": "group-name",
  "slug": "page-slug"
}
upload_group_wiki_attachment: Upload an attachment to a GitLab group wiki
{
  "group_id": "group-name",
  "file_path": "path/to/attachment.png",
  "content": "base64-encoded-content",
  "branch": "main"
}

🔧 Development

Requirements

  • Node.js 16+
  • npm 7+
  • A GitLab account with a personal access token

Building the Project

npm run build

Running Tests

npm test

Code Style and Linting

npm run lint

Release Process

  1. Update version in package.json
  2. Update CHANGELOG.md
  3. Create a new release on GitHub
  4. Publish to npm with npm publish

📖 Documentation

For more detailed documentation, please visit our documentation site or check the TypeScript definitions in the source code.

💼 Use Cases

  • AI-powered Development Workflows - Enable AI assistants to interact with your GitLab repositories
  • Automated Issue and PR Management - Streamline development processes with AI support
  • Wiki Management - Automate documentation updates and knowledge base management
  • Team Collaboration - Integrate AI assistants into your team’s GitLab workflow

📊 Roadmap

  • [ ] GitLab CI/CD Integration
  • [ ] Advanced Project Analytics
  • [ ] Comprehensive Test Suite
  • [ ] Support for GitLab GraphQL API
  • [ ] Extended Webhook Support

🤝 Contributing

Contributions are welcome and appreciated! Here’s how you can contribute:

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Please make sure to update tests as appropriate and follow the code style of the project.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

👥 Contributors

Thanks to all the contributors who have helped improve this project:

Special thanks to:

  • thomasleveil - Implemented GitLab member listing functionality for projects and groups with consistent response formatting

📦 NPM Package

This package is available on npm:
https://www.npmjs.com/package/@yoda.digital/gitlab-mcp-server

GitLab MCP Server

by yoda-digital
291 GitHub stars

Resources

Project Details

Categories

Developer Tools Productivity & Workflow Version Control

Recomended MCP Servers

🧩
mcp-server-shioaji
🧩
Figma Server

Model Context Protocol server implementation for Figma API
🧩
Firefly

Firefly MCP

 Lark Tools
Lark Tools

MCP server provides Feishu related operations to AI encoding agents such as cursor 飞书MCP插件，读取文档、发送消息、合同审批、数据处理.....
🧩
MCPet

This is a TypeScript-based Model Context Protocol (MCP) server that implements a virtual pet simulation system. It demonstrates...

 Gmail GAS
Gmail GAS
 Kubernetes Operations Manager
Kubernetes Operations Manager

kom 是一个用于 Kubernetes 操作的工具，SDK级的kubectl、client-go的使用封装。并且支持作为管理k8s 的 MCP server。 它提供了一系列功能来管理 Kubernetes 资源，包括创建、更新、删除和获取资源，甚至使用SQL查询k8s资源。这个项目支持多种 Kubernetes 资源类型的操作，并能够处理自定义资源定义（CRD）。 通过使用 kom，你可以轻松地进行资源的增删改查和日志获取以及操作POD内文件等动作。

 AI Image Generation Service
AI Image Generation Service

可用于cursor 集成 mcp server

 ServiceNow MCP Server
ServiceNow MCP Server
 GitLab Merge Request Integration
GitLab Merge Request Integration

Interact seamlessly with GitLab repositories to manage merge requests and issues. Fetch details, add comments, and streamline your...

 TfNSW Realtime Alerts
TfNSW Realtime Alerts

A Model Context Protocol (MCP) server for TfNSW's realtime alerts API
🧩
Weaviate MCP Server

A ready-to-use MCP (Model Context Protocol) server template for extending Cursor IDE with custom tools. Deploy your own...

Featured Templates

View More
Google Auth
Unified Authorization Template
172 578
FREE Install
AI Assistants
Image to text with Claude 3
150 1089
FREE Install
AI Agents
AI Video Generator
249 1323 5.0
FREE Install
AI Engineering
Calculate Time Complexity with ChatGPT API
137 2134
FREE Install
AI Image Generation
Image Generation with Stable Diffusion
113 654
FREE Install
AI Agents
AI Voice Assistant (Voice-Text-Voice)
169 1160 5.0
FREE Install

Start your free trial

Build your solution today. No credit card required.

Start for Free

Sign In

Don't have an account yet? Register

Forgot password?

Register

Reset Password

Please enter your username or email address, you will receive a link to create a new password via email.