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
-
Clone or download the server files:
bash # Files needed: # - gitlab-mcp-server.py # - gitlab-mcp-config.json -
Install Python dependencies:
bash pip install mcp -
Configure the server:
Editgitlab-mcp-config.jsonwith your GitLab instance details:json { "gitlab_url": "https://your-gitlab-instance.com", "access_token": "your-gitlab-token", "default_project_id": 1, "default_user_id": 1 } -
Set environment variables (optional):
bash 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):```json
{
"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```json
"github.com/modelcontextprotocol/servers/tree/main/src/git": {
"command": "python",
"args": ["-m", "mcp_server_git"],
"autoApprove": [],
"disabled": false,
"timeout": 60
}
Search Server```json
"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`)
| Field | Description | Required |
|-------|-------------|----------|
| `gitlab_url` | Your GitLab instance URL | Yes |
| `access_token` | GitLab Personal Access Token | Yes |
| `default_project_id` | Default project for operations | No |
| `default_user_id` | Default user for assignments | No |
### 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.```json
{
"project_id": 4,
"user_id": 5
}
list_closed_issues
Get closed issues assigned to a specific user.```json
{
"project_id": 4,
"user_id": 5
}
#### `close_issue`
Close a specific issue with optional comment.```json
{
"project_id": 4,
"issue_iid": 123,
"comment": "Issue resolved successfully"
}
reopen_issue
Reopen a closed issue with optional comment.```json
{
"project_id": 4,
"issue_iid": 123,
"comment": "Reopening for additional work"
}
#### `create_bug`
Create a new bug issue with "BUG: " prefix.```json
{
"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.```json
{
"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```bash
# 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```bash
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```bash
# List all open issues for a specific user
{
"tool": "list_open_issues",
"arguments": {
"user_id": 5
}
}
Development Workflow
- Project Planning: Create structured issues and organize them with labels and milestones
- Task Assignment: Assign issues to appropriate team members
- Progress Tracking: Monitor issue status and completion
- 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:bash
export GITLAB_MCP_DEBUG=true
Contributing
To extend the server with new tools:
- Add tool definition in
handle_list_tools() - Implement tool logic in
handle_call_tool() - Update configuration schema if needed
- 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
