mcp gitlab server

Local 2025-08-31 23:17:44 0
Developer Tools @yoda-digital/mcp-gitlab-server

GitLab MCP Server (with activity tracking and group projects listing features)

This server is based on the original GitLab MCP server with Group Projects Listing and Activity Tracking enhancements

A Model Context Protocol (MCP) server for GitLab integration, providing tools to interact with GitLab repositories, issues, merge requests, wikis, and more.

Features

  • Support for both stdio and SSE transports
  • Strict TypeScript typing with the MCP SDK
  • Comprehensive GitLab API integration
  • Repository operations (search, create, fork)
  • File operations (read, create, update)
  • Branch operations (create)
  • Issue management (create, list, filter)
  • Merge request handling (create, list, filter)
  • Group projects listing
  • Project events retrieval
  • Commit history access
  • Member management (list project and group members)
  • Complete wiki management:
  • Project wiki support (list, get, create, edit, delete pages)
  • Group wiki support (list, get, create, edit, delete pages)
  • Wiki attachment handling
  • Multiple wiki formats (markdown, rdoc, asciidoc, org)

Installation

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

From Source

# Clone the repository
git clone https://github.com/yourusername/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 when running directly:

  • GITLAB_PERSONAL_ACCESS_TOKEN (required): Your GitLab personal access token
  • GITLAB_API_URL (optional): The GitLab API URL (defaults to 'https://gitlab.com/api/v4')
  • PORT (optional): The port to use for SSE transport (defaults to 3000)
  • USE_SSE (optional): Set to 'true' to use SSE transport instead of stdio (defaults to 'false')

MCP Settings Configuration

You can add the GitLab MCP server to your MCP settings file (e.g., cline_mcp_settings.json or claude_desktop_config.json):

{
  "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
    }
  }
}

Usage

Running with stdio transport (default)

# Set your GitLab personal access token
export GITLAB_PERSONAL_ACCESS_TOKEN=your_token_here

# Run the server
npm start

Running with SSE transport

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

# Run the server
npm start

Running with npx

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

Available Tools

The server provides the following 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
}

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
}
  • 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
}

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

Building the Project

npm run build

Running Tests

npm test

License

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

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Contributors

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

  • thomasleveil - Implemented GitLab member listing functionality for projects and groups

NPM Package

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