GitLab MCP Server

A Model Context Protocol (MCP) server for interacting with GitLab repositories with enhanced functionality.

Overview

This MCP server allows AI assistants (like Claude) to interact with GitLab repositories, manage projects, issues, merge requests, and more. It extends the original implementation with additional endpoints and improved error handling.

Features

• Project Management

  • Create new repositories (with improved group namespace support)
  • Update project settings (including visibility)
  • Delete projects
  • Fork projects
  • Search for repositories

• File Operations

  • Fetch file contents
  • Create or update files
  • Commit multiple files at once

• Repository Management

  • Create branches
  • Create issues
  • Create merge requests

• Issues and Time Tracking

  • Get issues with filtering options
  • Get detailed issue information
  • Manage time tracking (estimates and spent time)
  • View time tracking statistics
  • Update issue attributes
  • Close and reopen issues

• Notes (Comments)

  • Retrieve issue comments
  • Create new comments
  • Update existing comments
  • Delete comments

• Label Management

  • Get project labels
  • Create, update, and delete labels
  • Add labels to issues
  • Remove labels from issues

• Milestone Management

  • Get project milestones
  • Create new milestones

• User Assignment

  • Assign users to issues
  • Remove assignees from issues

• Issue Relationships

  • Create links between issues
  • Delete issue links

Installation

Global Installation

npm install -g @piatra-open-source/gitlab-mcp-server

Project Installation

npm install @piatra-open-source/gitlab-mcp-server

Usage

Environment Variables

You need to set the following environment variables:

• GITLAB_PERSONAL_ACCESS_TOKEN: Your GitLab personal access token with appropriate permissions
• GITLAB_API_URL (optional): Custom GitLab API URL if not using gitlab.com (defaults to 'https://gitlab.com/api/v4')

Running the Server

export GITLAB_PERSONAL_ACCESS_TOKEN='your_token_here'
gitlab-mcp-server

Or in your application:

import { execFileSync } from 'child_process';
import { join } from 'path';

// Path to the GitLab MCP Server binary
const serverPath = join(require.resolve('@piatra-open-source/gitlab-mcp-server'), '..', '..', 'bin', 'gitlab-mcp-server');

// Start the server
const childProcess = execFileSync(serverPath, {
  env: {
    ...process.env,
    GITLAB_PERSONAL_ACCESS_TOKEN: 'your_token_here'
  }
});

API Reference

Functions

| Function Name | Description | |---------------|-------------| | create_repository | Create a new GitLab project | | update_project | Update project settings including visibility | | delete_project | Delete a GitLab project | | search_repositories | Search for GitLab projects | | get_file_contents | Get file or directory contents | | create_or_update_file | Create or update a single file | | push_files | Commit multiple files at once | | create_branch | Create a new branch | | fork_repository | Fork a project | | create_issue | Create a new issue | | create_merge_request | Create a new merge request | | get_issues | Get issues from a project with filtering options | | get_issue | Get a single issue with details | | get_issue_time_stats | Get time tracking statistics for an issue | | set_time_estimate | Set time estimate for an issue | | reset_time_estimate | Reset time estimate for an issue | | add_spent_time | Add spent time to an issue | | reset_spent_time | Reset spent time for an issue | | get_notes | Get comments/notes for an issue | | create_note | Create a comment on an issue | | update_note | Update an existing comment | | delete_note | Delete a comment from an issue | | update_issue | Update various issue attributes | | close_issue | Close an issue | | reopen_issue | Reopen a closed issue | | get_project_labels | Retrieve all labels for a project | | create_project_label | Create a new label for a project | | update_project_label | Update an existing label | | delete_project_label | Delete a label from a project | | add_labels_to_issue | Add specific labels to an issue | | remove_labels_from_issue | Remove specific labels from an issue | | get_project_milestones | Retrieve all milestones for a project | | create_project_milestone | Create a new milestone for a project | | assign_issue | Assign users to an issue | | unassign_issue | Remove all assignees from an issue | | create_issue_link | Create a link between two issues | | delete_issue_link | Remove a link between issues |

Example Usage

// Example: Create a repository in a specific group
const repo = await claude.callMcp("gitlab", "create_repository", {
  name: "my-new-project",
  description: "A new project created via MCP",
  visibility: "private",
  initialize_with_readme: true,
  namespace_id: "12345678"  // Group ID where the project should be created
});

// Example: Change project visibility
const updatedRepo = await claude.callMcp("gitlab", "update_project", {
  project_id: "12345678",
  visibility: "private"
});

// Example: Delete a project
const deleteResult = await claude.callMcp("gitlab", "delete_project", {
  project_id: "12345678"
});

// Example: Get all issues with time tracking stats
const issues = await claude.callMcp("gitlab", "get_issues", {
  project_id: "12345678",
  state: "opened",
  with_time_stats: true
});

// Example: Add spent time to an issue
const timeStats = await claude.callMcp("gitlab", "add_spent_time", {
  project_id: "12345678", 
  issue_iid: 42,
  duration: "1h 30m" // Format: Xh Ym
});

// Example: Get all comments on an issue
const notes = await claude.callMcp("gitlab", "get_notes", {
  project_id: "12345678",
  issue_iid: 42,
  sort: "desc",
  order_by: "created_at"
});

// Example: Update an issue
const updatedIssue = await claude.callMcp("gitlab", "update_issue", {
  project_id: "12345678",
  issue_iid: 42,
  title: "Updated issue title",
  description: "This is the updated description"
});

// Example: Create a label
const newLabel = await claude.callMcp("gitlab", "create_project_label", {
  project_id: "12345678",
  name: "enhancement",
  color: "#428BCA",
  description: "Enhancement requests"
});

// Example: Add labels to an issue
const issueWithLabels = await claude.callMcp("gitlab", "add_labels_to_issue", {
  project_id: "12345678",
  issue_iid: 42,
  labels: ["bug", "enhancement"]
});

// Example: Create a milestone
const milestone = await claude.callMcp("gitlab", "create_project_milestone", {
  project_id: "12345678",
  title: "v1.0 Release",
  description: "First stable release",
  due_date: "2025-06-30"
});

// Example: Assign users to an issue
const assignedIssue = await claude.callMcp("gitlab", "assign_issue", {
  project_id: "12345678",
  issue_iid: 42,
  assignee_ids: [123, 456]
});

// Example: Create a link between issues
const issueLink = await claude.callMcp("gitlab", "create_issue_link", {
  project_id: "12345678",
  issue_iid: 42,
  target_project_id: "12345678",
  target_issue_iid: 43,
  link_type: "relates_to"
});

Improvements Over Original Implementation

This implementation includes several enhancements over the original MCP GitLab server:

1. Comprehensive API endpoints:

   • delete_project: Properly delete GitLab projects
   • update_project: Update project settings including visibility
   • get_issues & get_issue: Retrieve issues with filtering options
   • Time tracking endpoints: Set/reset estimates and spent time
   • Notes endpoints: Create, read, update, delete comments
   • Label management: Create, retrieve, update, and delete labels
   • Milestone management: Get milestones and create new ones
   • User assignment: Assign and unassign users to/from issues
   • Issue relationships: Create and delete links between issues

2. Fixed namespace_id handling:

   • Properly supports creating projects in group namespaces
   • Validates and passes namespace_id to the GitLab API

3. Enhanced error handling:

   • Detailed error messages including API response data
   • Improved validation of input parameters
   • Better feedback on authentication and permission issues

4. Updated documentation:

   • Clear documentation of all supported parameters
   • More complete type definitions

Troubleshooting

"file_path should be a valid file path" Error

If you encounter the error GitLab API error (400): Bad Request - file_path should be a valid file path, there are several possible causes:

1. File Path Format: GitLab expects file paths to be valid and properly formatted. Make sure your file path:

   • Does not contain invalid characters like *, ?, [, ] etc.
   • Uses forward slashes (/) not backslashes (\)
   • Is properly URL-encoded (handled by this library)

2. Case Sensitivity: GitLab file paths are case-sensitive. Ensure your paths match the exact case of existing files.

3. Repository Structure: The file path must exist in the repository structure for updates, or be valid for new files.

4. Special Characters: Avoid using special characters in file names when possible. If you need to use characters like #, ?, [, ], be aware that they might require special handling.

Other Common Issues

• Authentication Failures: Make sure your GITLAB_PERSONAL_ACCESS_TOKEN has the necessary permissions.
• Permission Denied: Ensure you have proper access rights to the repository and group.
• Rate Limiting: GitLab API has rate limits that may temporarily block your access if exceeded.

License

MIT

Attribution

This project is an enhanced version of the original Model Context Protocol GitLab server by Anthropic, modified and extended under the MIT license.