@dangerusslee/gitlab-mcp-server
v0.3.2
Published
GitLab MCP Server - A Model Context Protocol server for GitLab integration
Downloads
14
Maintainers
Readme
GitLab MCP Server
✨ Features
- Comprehensive GitLab API Integration - Access repositories, issues, merge requests, wikis, runners 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
- CI/CD Pipeline Integration - Validate CI YAML configurations and trigger pipelines with job insights
- Runner Management - Comprehensive GitLab runner administration with full lifecycle control
🔍 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
- CI/CD Pipelines - Validate CI YAML configurations, trigger runs, inspect jobs
- Runner Management - Register, list, update, delete, and manage GitLab runners
- 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 @dangerusslee/gitlab-mcp-serverFrom Source
# Clone the repository
git clone https://github.com/dangerusslee/mcp-gitlab-server.git
cd mcp-gitlab-server
# Install dependencies
npm install
# Build the project
npm run buildConfiguration
Environment Variables
The server requires the following environment variables:
| Variable | Required | Default | Description |
| ------------------------------ | -------- | --------------------------- | -------------------------------------------------- |
| GITLAB_PERSONAL_ACCESS_TOKEN | Yes | - | Your GitLab personal access token |
| GITLAB_API_URL | No | https://gitlab.com/api/v4 | GitLab API URL |
| PORT | No | 3000 | Port for SSE transport |
| USE_SSE | No | false | Set to 'true' to use SSE transport |
| GITLAB_READ_ONLY_MODE | No | false | Set 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_repositoriesget_file_contentslist_group_projectsget_project_eventslist_commitslist_issueslist_merge_requestslist_project_wiki_pagesget_project_wiki_pagelist_group_wiki_pagesget_group_wiki_pagelist_project_memberslist_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", "@dangerusslee/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", "@dangerusslee/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 startWith 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 startWith npx
# Run directly with npx
GITLAB_PERSONAL_ACCESS_TOKEN=your_token_here npx @dangerusslee/gitlab-mcp-server🛠️ Available Tools
Repository Operations
{
"search": "project-name",
"page": 1,
"per_page": 20
}{
"name": "new-project",
"description": "A new project",
"visibility": "private",
"initialize_with_readme": true
}{
"project_id": "username/project",
"namespace": "target-namespace"
}{
"group_id": "group-name",
"archived": false,
"visibility": "public",
"include_subgroups": true,
"page": 1,
"per_page": 20
}File Operations
{
"project_id": "username/project",
"file_path": "path/to/file.txt",
"ref": "main"
}{
"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"
}{
"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
{
"project_id": "username/project",
"branch": "new-branch",
"ref": "main"
}Issue Operations
{
"project_id": "username/project",
"title": "Issue title",
"description": "Issue description",
"assignee_ids": [1, 2],
"milestone_id": 1,
"labels": ["bug", "critical"]
}{
"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
}{
"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
]
}{
"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
{
"project_id": "username/project",
"title": "Merge request title",
"description": "Merge request description",
"source_branch": "feature-branch",
"target_branch": "main",
"allow_collaboration": true,
"draft": false
}{
"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
{
"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
}{
"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
}Pipeline Operations
{
"project_id": "username/project",
"content": "CI configuration as YAML",
"include_merged_yaml": true
}Parameters:
project_id(required): Project identifier (e.g., "71771195" or "username/project")content(optional): YAML content to validate. If not provided, reads.gitlab-ci.ymlfrom the project's main branchinclude_merged_yaml(optional): Whether to include the merged YAML in the response. Defaults totrue
Response Format:
{
"valid": true,
"errors": [],
"warnings": ["Warning message if any"],
"merged_yaml": "stages:\n - build\n - test\n...",
"includes": []
}Usage Examples:
- Validate existing project CI configuration:
{
"project_id": "71771195"
}- Validate custom YAML content:
{
"project_id": "username/project",
"content": "stages:\n - build\n - test\n\nbuild_job:\n stage: build\n script:\n - echo 'Building...'\n",
"include_merged_yaml": false
}- Validate with merged YAML output:
{
"project_id": "testing7075939/ami-rhel9-gold",
"include_merged_yaml": true
}API Call Pattern:
curl -X POST "https://gitlab.com/api/v4/projects/{project_id}/ci/lint" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${GITLAB_PERSONAL_ACCESS_TOKEN}" \
--data '{"content": "yaml_content_here", "include_merged_yaml": true}'{
"project_id": "username/project",
"ref": "main",
"variables": {
"KEY": "value"
}
}{
"project_id": "username/project",
"pipeline_id": 123
}{
"project_id": "username/project",
"pipeline_id": 123
}{
"project_id": "username/project",
"job_id": 456
}{
"project_id": "username/project",
"job_id": 456
}Runner Management
GitLab Runners are the agents that execute CI/CD jobs. This server provides comprehensive runner management capabilities, including registration, monitoring, and administration of project-specific, group-specific, and instance-wide runners.
Authentication Requirements
Runner management operations require appropriate GitLab permissions:
- Project Runners: Maintainer access to the specific project
- Group Runners: Owner access to the group
- Instance Runners: Admin access to the GitLab instance
- Registration: Requires valid registration tokens from project/group/instance settings
Error Handling
All runner operations include comprehensive error handling:
{
"error": "Runner not found",
"status": 404,
"details": "No runner found with ID 12345"
}Common error scenarios:
- 403 Forbidden: Insufficient permissions for the operation
- 404 Not Found: Runner, project, or group does not exist
- 400 Bad Request: Invalid parameters or registration token
- 422 Unprocessable Entity: Validation errors in runner configuration
{
"project_id": "username/project",
"token": "project-registration-token",
"description": "My Project Runner",
"tag_list": ["docker", "linux", "production"],
"run_untagged": false,
"locked": true,
"access_level": "not_protected",
"maximum_timeout": 3600
}Parameters:
project_id(required): Project identifier (e.g., "username/project" or "12345")token(required): Project registration token from Project Settings > CI/CD > Runnersdescription(optional): Human-readable description for the runnertag_list(optional): Array of tags to assign to the runnerrun_untagged(optional): Whether runner can execute jobs without tags (default: true)locked(optional): Whether runner is locked to current project (default: false)access_level(optional): "not_protected" or "ref_protected" (default: "not_protected")maximum_timeout(optional): Maximum job timeout in seconds
Response Format:
{
"id": 12345,
"token": "runner-authentication-token",
"description": "My Project Runner",
"active": true,
"paused": false,
"is_shared": false,
"runner_type": "project_type",
"name": null,
"online": false,
"status": "offline"
}Usage Examples:
- Basic project runner registration:
{
"project_id": "mygroup/myproject",
"token": "GR1348941abc123def456",
"description": "Production Docker Runner"
}- Advanced runner with specific configuration:
{
"project_id": "12345",
"token": "GR1348941abc123def456",
"description": "Specialized Build Runner",
"tag_list": ["docker", "linux", "build"],
"run_untagged": false,
"locked": true,
"access_level": "ref_protected",
"maximum_timeout": 7200
}{
"group_id": "my-group",
"token": "group-registration-token",
"description": "My Group Runner",
"tag_list": ["docker", "linux"],
"run_untagged": true,
"access_level": "not_protected",
"maximum_timeout": 3600
}Parameters:
group_id(required): Group identifier (e.g., "my-group" or "67890")token(required): Group registration token from Group Settings > CI/CD > Runnersdescription(optional): Human-readable description for the runnertag_list(optional): Array of tags to assign to the runnerrun_untagged(optional): Whether runner can execute jobs without tags (default: true)access_level(optional): "not_protected" or "ref_protected" (default: "not_protected")maximum_timeout(optional): Maximum job timeout in seconds
Response Format:
{
"id": 12346,
"token": "runner-authentication-token",
"description": "My Group Runner",
"active": true,
"paused": false,
"is_shared": false,
"runner_type": "group_type",
"name": null,
"online": false,
"status": "offline"
}{
"project_id": "username/project",
"scope": "active",
"type": "project_type",
"status": "online",
"tag_list": ["docker", "linux"],
"page": 1,
"per_page": 20
}Parameters:
project_id(required): Project identifierscope(optional): Filter by scope - "active", "paused", "online", "offline"type(optional): Filter by type - "instance_type", "group_type", "project_type"status(optional): Filter by status - "online", "offline", "stale", "never_contacted"tag_list(optional): Array of tags to filter bypage(optional): Page number for pagination (default: 1)per_page(optional): Number of results per page (default: 20, max: 100)
Response Format:
{
"count": 3,
"items": [
{
"id": 12345,
"description": "My Project Runner",
"ip_address": "192.168.1.100",
"active": true,
"paused": false,
"is_shared": false,
"runner_type": "project_type",
"name": null,
"online": true,
"status": "online",
"created_at": "2023-01-01T00:00:00Z",
"contacted_at": "2023-01-02T12:30:00Z",
"architecture": "linux/amd64",
"platform": "linux",
"projects": [
{
"id": 123,
"name": "myproject",
"name_with_namespace": "mygroup/myproject"
}
],
"groups": [],
"version": "15.8.0",
"access_level": "not_protected",
"maximum_timeout": 3600,
"tag_list": ["docker", "linux", "production"]
}
]
}{
"group_id": "my-group",
"type": "group_type",
"status": "online",
"tag_list": ["docker"],
"page": 1,
"per_page": 20
}Parameters:
group_id(required): Group identifiertype(optional): Filter by type - "instance_type", "group_type"status(optional): Filter by status - "online", "offline", "stale", "never_contacted"tag_list(optional): Array of tags to filter bypage(optional): Page number for paginationper_page(optional): Number of results per page
Response Format:
{
"count": 2,
"items": [
{
"id": 12346,
"description": "My Group Runner",
"ip_address": "192.168.1.101",
"active": true,
"paused": false,
"is_shared": false,
"runner_type": "group_type",
"name": null,
"online": true,
"status": "online",
"created_at": "2023-01-01T00:00:00Z",
"contacted_at": "2023-01-02T12:30:00Z",
"architecture": "linux/amd64",
"platform": "linux",
"projects": [],
"groups": [
{
"id": 456,
"name": "my-group",
"full_name": "my-group"
}
],
"version": "15.8.0",
"access_level": "not_protected",
"maximum_timeout": 3600,
"tag_list": ["docker", "linux"]
}
]
}{
"scope": "active",
"type": "instance_type",
"status": "online",
"tag_list": ["shared"],
"page": 1,
"per_page": 20
}Parameters:
scope(optional): Filter by scope - "active", "paused", "online", "offline"type(optional): Filter by type - "instance_type", "group_type", "project_type"status(optional): Filter by status - "online", "offline", "stale", "never_contacted"tag_list(optional): Array of tags to filter bypage(optional): Page number for paginationper_page(optional): Number of results per page
Authentication: Requires GitLab admin privileges
{
"runner_id": 12345
}Parameters:
runner_id(required): Runner ID
Response Format:
{
"id": 12345,
"description": "My Project Runner",
"ip_address": "192.168.1.100",
"active": true,
"paused": false,
"is_shared": false,
"runner_type": "project_type",
"name": null,
"online": true,
"status": "online",
"created_at": "2023-01-01T00:00:00Z",
"contacted_at": "2023-01-02T12:30:00Z",
"architecture": "linux/amd64",
"platform": "linux",
"projects": [
{
"id": 123,
"name": "myproject",
"name_with_namespace": "mygroup/myproject"
}
],
"groups": [],
"version": "15.8.0",
"revision": "abc123def",
"access_level": "not_protected",
"maximum_timeout": 3600,
"tag_list": ["docker", "linux", "production"],
"run_untagged": false,
"locked": true
}{
"runner_id": 12345,
"description": "Updated Runner Description",
"active": true,
"tag_list": ["docker", "linux", "updated"],
"run_untagged": true,
"locked": false,
"access_level": "ref_protected",
"maximum_timeout": 7200
}Parameters:
runner_id(required): Runner IDdescription(optional): New description for the runneractive(optional): Whether the runner is activetag_list(optional): New array of tags (replaces existing tags)run_untagged(optional): Whether runner can execute jobs without tagslocked(optional): Whether runner is locked to current projectsaccess_level(optional): "not_protected" or "ref_protected"maximum_timeout(optional): Maximum job timeout in seconds
Response Format:
{
"id": 12345,
"description": "Updated Runner Description",
"active": true,
"paused": false,
"is_shared": false,
"runner_type": "project_type",
"tag_list": ["docker", "linux", "updated"],
"run_untagged": true,
"locked": false,
"access_level": "ref_protected",
"maximum_timeout": 7200
}{
"runner_id": 12345
}Parameters:
runner_id(required): Runner ID
Response Format:
{
"id": 12345,
"description": "My Project Runner",
"active": false,
"paused": true,
"status": "paused"
}{
"runner_id": 12345
}Parameters:
runner_id(required): Runner ID
Response Format:
{
"id": 12345,
"description": "My Project Runner",
"active": true,
"paused": false,
"status": "online"
}{
"runner_id": 12345
}Parameters:
runner_id(required): Runner ID
Response Format:
{
"message": "Runner deleted successfully",
"runner_id": 12345
}⚠️ Warning: This operation is irreversible. The runner will be permanently removed and will need to be re-registered if required again.
Member Operations
{
"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
]
}{
"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
{
"project_id": "username/project",
"with_content": false
}{
"project_id": "username/project",
"slug": "page-slug",
"render_html": false,
"version": "commit-sha"
}{
"project_id": "username/project",
"title": "Page Title",
"content": "Wiki page content",
"format": "markdown"
}{
"project_id": "username/project",
"slug": "page-slug",
"title": "New Page Title",
"content": "Updated wiki page content",
"format": "markdown"
}{
"project_id": "username/project",
"slug": "page-slug"
}{
"project_id": "username/project",
"file_path": "path/to/attachment.png",
"content": "base64-encoded-content",
"branch": "main"
}Group Wiki Operations
{
"group_id": "group-name",
"with_content": false
}{
"group_id": "group-name",
"slug": "page-slug",
"render_html": false,
"version": "commit-sha"
}{
"group_id": "group-name",
"title": "Page Title",
"content": "Wiki page content",
"format": "markdown"
}{
"group_id": "group-name",
"slug": "page-slug",
"title": "New Page Title",
"content": "Updated wiki page content",
"format": "markdown"
}{
"group_id": "group-name",
"slug": "page-slug"
}{
"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 buildRunning Tests
npm testUtility Functions
Helper utilities simplify working with the GitLab API. isValidISODate
validates ISO 8601 strings, while formatting helpers like
formatEventsResponse convert raw responses into concise output.
Code Style and Linting
npm run lintRelease Process
- Update version in
package.json - Update CHANGELOG.md
- Create a new release on GitHub
- 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
- Runner Administration - Automate GitLab runner lifecycle management and monitoring
- Wiki Management - Automate documentation updates and knowledge base management
- Team Collaboration - Integrate AI assistants into your team's GitLab workflow
📊 Roadmap
- [x] GitLab CI/CD Integration
- [x] CI YAML Validation with GitLab Lint API
- [x] Runner Management (Registration, listing, updating, lifecycle control)
- [ ] Advanced Project Analytics
- [x] Comprehensive Test Suite
- [ ] Support for GitLab GraphQL API
- [ ] Extended Webhook Support
🤝 Contributing
Contributions are welcome and appreciated! Here's how you can contribute:
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - 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/@dangerusslee/gitlab-mcp-server
