FalkoGuderian/gitlab-mcp-server

GitLab MCP Server

A comprehensive GitLab automation server built on the Model Context Protocol (MCP) for streamlined project management and development workflow automation.

Overview

The GitLab MCP Server provides a powerful set of tools for automating GitLab operations, enabling seamless integration with development workflows, intelligent task assignment, and hierarchical project management. It supports both admin and non-admin modes with different capability sets based on user permissions.

Features

Core Capabilities

• Issue Management: Create, assign, close, and reopen issues with intelligent automation
• User Management: Comprehensive user operations and role-based access control
• Project Management: Full project lifecycle management with member administration

Installation

Prerequisites

• Python 3.8 or higher
• GitLab instance with API access
• GitLab Personal Access Token with appropriate permissions

Setup Steps

1. Clone or download the server files:

   # Files needed:
   # - gitlab-mcp-server.py
   # - gitlab-mcp-config.json
   

2. Install Python dependencies:

   pip install mcp
   

3. Configure the server: Edit gitlab-mcp-config.json with your GitLab instance details:

 {
   "gitlab_url": "https://your-gitlab-instance.com",
   "access_token": "your-gitlab-token",
   "default_project_id": 1,
   "default_user_id": 1
 }

4. Set environment variables (optional):

   export DEFAULT_GITLAB_PROJECT_ID=1
   export DEFAULT_GITLAB_USER_ID=1
   export GITLAB_MCP_ADMIN_MODE=false
   

   Note: gitlab_url and access_token must be configured in the gitlab-mcp-config.json file, not as environment variables.

MCP Configuration

To integrate this GitLab MCP Server with your development environment, add the following configuration to your MCP settings file (typically located at ~/.cline/mcp-settings.json or in your IDE's MCP configuration):

{
  "mcpServers": {
    "gitlab": {
      "command": "python",
      "args": [
        "<base-directory>\\gitlab-mcp-server.py"
      ],
      "env": {
        "GITLAB_TOKEN": "your-gitlab-token-here",
        "GITLAB_URL": "http://localhost",
        "DEFAULT_GITLAB_PROJECT_ID": "4",
        "DEFAULT_GITLAB_USER_ID": "5",
        "GITLAB_MCP_ADMIN_MODE": "false"
      },
      "autoApprove": [
        "list_gitlab_users",
        "list_project_issues",
        "list_assignee_open_tasks"
      ],
      "disabled": false,
      "timeout": 60
    }
  }
}

Additional MCP Servers

The configuration also supports additional MCP servers for enhanced functionality:

Git Server

"github.com/modelcontextprotocol/servers/tree/main/src/git": {
  "command": "python",
  "args": ["-m", "mcp_server_git"],
  "autoApprove": [],
  "disabled": false,
  "timeout": 60
}

Search Server

"github.com/NightTrek/Serper-search-mcp": {
  "command": "node",
  "args": ["d:/Projects/mcp/serper-search-server/build/index.js"],
  "env": {
    "SERPER_API_KEY": "your-serper-api-key",
    "OPENROUTER_API_KEY": "your-openrouter-api-key"
  },
  "autoApprove": [],
  "disabled": false,
  "timeout": 60
}

Configuration Options

• autoApprove: List of tool names that can be executed without manual approval
• disabled: Set to true to disable the server
• timeout: Request timeout in seconds
• env: Environment variables passed to the server process

Configuration

Basic Configuration (gitlab-mcp-config.json)

Access Token Permissions

For full functionality, your GitLab Personal Access Token should have:

• read_api - Read access to API
• read_user - Read user information
• read_repository - Read repository data
• write_repository - Write repository data
• api - Full API access (for admin operations)

Admin Mode vs Non-Admin Mode

Admin Mode (admin_mode: true):

• Full access to all tools
• Can delete issues
• Can manage all projects and users
• Can perform bulk operations

Non-Admin Mode (admin_mode: false):

• Limited to assignee-related operations
• Can only work with assigned issues
• Cannot delete issues
• Cannot access user management tools

Available Tools

Issue Management Tools

list_open_issues

Get open issues assigned to a specific user.

{
  "project_id": 4,
  "user_id": 5
}

list_closed_issues

Get closed issues assigned to a specific user.

{
  "project_id": 4,
  "user_id": 5
}

close_issue

Close a specific issue with optional comment.

{
  "project_id": 4,
  "issue_iid": 123,
  "comment": "Issue resolved successfully"
}

reopen_issue

Reopen a closed issue with optional comment.

{
  "project_id": 4,
  "issue_iid": 123,
  "comment": "Reopening for additional work"
}

create_bug

Create a new bug issue with "BUG: " prefix.

{
  "project_id": 4,
  "title": "Login button not working",
  "description": "Users cannot log in when clicking the login button",
  "labels": ["bug", "urgent"],
  "assignee_id": 5
}

delete_all_project_issues (Admin Only)

Delete all issues in a project.

{
  "project_id": 4
}

User Management Tools (Admin Only)

list_gitlab_users

Get all users in the GitLab instance.

list_project_issues

Get all issues in a project.

Usage Examples

Creating a Bug Report

# Using the MCP server to create a bug
{
  "tool": "create_bug",
  "arguments": {
    "title": "Authentication failure on mobile devices",
    "description": "Users are experiencing login issues when accessing the application from mobile browsers.",
    "labels": ["bug", "mobile", "authentication"],
    "assignee_id": 5
  }
}

Managing Issue Lifecycle

# Close an issue with a comment
{
  "tool": "close_issue",
  "arguments": {
    "issue_iid": 123,
    "comment": "Fixed in commit abc123. Tested on multiple browsers."
  }
}

Getting User Assignments

# List all open issues for a specific user
{
  "tool": "list_open_issues",
  "arguments": {
    "user_id": 5
  }
}

Development Workflow

1. Project Planning: Create structured issues and organize them with labels and milestones
2. Task Assignment: Assign issues to appropriate team members
3. Progress Tracking: Monitor issue status and completion
4. Quality Assurance: Use labels and milestones for organization

Error Handling

The server provides comprehensive error handling for:

• Network Issues: Connection problems with GitLab API
• Authentication Errors: Invalid or expired tokens
• Permission Errors: Insufficient permissions for operations
• Validation Errors: Invalid parameters or missing required fields

Security Considerations

• Store access tokens securely (environment variables recommended)
• Use minimal required permissions for tokens
• Enable admin mode only when necessary
• Regularly rotate access tokens
• Monitor API usage and rate limits

Troubleshooting

Common Issues

"GitLab API not configured"

• Ensure gitlab_url and access_token are set in config
• Verify token has required permissions

"No project_id provided"

• Set default_project_id in config or provide in tool arguments
• Verify project exists and is accessible

"Permission denied"

• Check access token permissions
• Verify user has access to specified project
• Consider admin mode requirements

Debug Mode

Enable debug logging by setting environment variable:

export GITLAB_MCP_DEBUG=true

Contributing

To extend the server with new tools:

1. Add tool definition in handle_list_tools()
2. Implement tool logic in handle_call_tool()
3. Update configuration schema if needed
4. Add tests and documentation

License

MIT License - feel free to use this project in your own applications.

Support

For issues and questions:

• Check the troubleshooting section
• Verify your GitLab instance configuration
• Ensure all prerequisites are met
• Review access token permissions