Skip to main content
Glama

GitLab MCP Server

by Alosies
npmGitHub
JavaScript
301
1
  • Apple
OverviewInspectNewSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

GitLab MCP Server

A fully typed TypeScript Model Context Protocol (MCP) server that provides comprehensive integration with GitLab's REST API. This server allows you to interact with GitLab projects, issues, merge requests, pipelines, jobs, and more through the MCP protocol with complete type safety.

Features

  • Projects: List projects, get project details
  • Issues: List, get, and create issues
  • Merge Requests: List, get, and create merge requests
  • Pipelines: List, get, create, retry, cancel, and delete pipelines
  • Pipeline Jobs: List jobs within pipelines
  • Pipeline Variables: Get pipeline variables
  • Job Logs: Get log files (traces) for specific jobs
  • Branches: List repository branches
  • Commits: Get project commit history
  • User: Get current user information
  • TypeScript: Fully typed with comprehensive type definitions
  • Developer Experience: Complete IntelliSense and type safety

Prerequisites

  • Node.js 18+ and npm
  • GitLab personal access token
  • TypeScript 5.0+ (for development or type-checking)

Installation

No installation required! Claude Desktop will automatically download and run the latest version:

{ "mcpServers": { "gitlab": { "command": "npx", "args": ["-y", "@alosies/gitlab-mcp-server"], "env": { "NPM_CONFIG_TOKEN": "your-gitlab-token-here" } } } }

Option 2: Global Installation

npm install -g @alosies/gitlab-mcp-server

Then use in Claude Desktop:

{ "mcpServers": { "gitlab": { "command": "gitlab-mcp-server", "env": { "NPM_CONFIG_TOKEN": "your-gitlab-token-here" } } } }

Option 3: Development from Source

  1. Clone this repository
  2. Install dependencies: npm install
  3. Build the TypeScript code: npm run build
  4. Use in Claude Desktop with full path

Configuration

The server requires a GitLab personal access token to authenticate with the GitLab API. You need to set this token in the NPM_CONFIG_TOKEN environment variable.

Creating a GitLab Personal Access Token

  1. Go to GitLab.com (or your GitLab instance)
  2. Navigate to Settings > Access Tokens
  3. Create a new token with the following scopes:
    • api - Full API access
    • read_user - Read user information
    • read_repository - Read repository data

Environment Setup

Set your GitLab token as an environment variable:

export NPM_CONFIG_TOKEN="your-gitlab-token-here"

Or create a .env file (not recommended for production):

NPM_CONFIG_TOKEN=your-gitlab-token-here

Usage

Running the Server

With npx (recommended):

npx -y @alosies/gitlab-mcp-server

If installed globally:

gitlab-mcp-server

Development from source:

npm start # or for auto-rebuild: npm run dev

⚠️ Security Note: Never commit your GitLab token to version control. The token in the example above is just a placeholder.

Configuring with Claude Desktop

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

Recommended: Using npx (always gets latest version):

{ "mcpServers": { "gitlab": { "command": "npx", "args": ["-y", "@alosies/gitlab-mcp-server"], "env": { "NPM_CONFIG_TOKEN": "your-gitlab-token-here" } } } }

Alternative: Global installation:

npm install -g @alosies/gitlab-mcp-server
{ "mcpServers": { "gitlab": { "command": "gitlab-mcp-server", "env": { "NPM_CONFIG_TOKEN": "your-gitlab-token-here" } } } }

Development: From source:

{ "mcpServers": { "gitlab": { "command": "node", "args": ["/path/to/gitlab-mcp-server/dist/index.js"], "env": { "NPM_CONFIG_TOKEN": "your-gitlab-token-here" } } } }

Available Tools

Project Management

  • list_projects: List GitLab projects
    • Optional filters: search, visibility, owned, per_page
  • get_project: Get detailed information about a specific project
    • Required: project_id (ID or path like "group/project")

Issue Management

  • list_issues: List issues in a project
    • Required: project_id
    • Optional filters: state, labels, assignee_id, author_id, search, per_page
  • get_issue: Get detailed information about a specific issue
    • Required: project_id, issue_iid
  • create_issue: Create a new issue
    • Required: project_id, title
    • Optional: description, labels, assignee_ids, milestone_id

Merge Request Management

  • list_merge_requests: List merge requests in a project
    • Required: project_id
    • Optional filters: state, target_branch, source_branch, assignee_id, author_id, search, per_page
  • get_merge_request: Get detailed information about a specific merge request
    • Required: project_id, merge_request_iid
  • create_merge_request: Create a new merge request
    • Required: project_id, title, source_branch, target_branch
    • Optional: description, assignee_ids, reviewer_ids, labels, milestone_id

Repository Operations

  • list_project_branches: List branches in a project
    • Required: project_id
    • Optional: search, per_page
  • get_project_commits: Get commit history for a project
    • Required: project_id
    • Optional: ref_name, since, until, author, per_page

Pipeline Management

  • list_pipelines: List pipelines in a project
    • Required: project_id
    • Optional filters: status, ref, sha, yaml_errors, name, username, updated_after, updated_before, order_by, sort, per_page
  • get_pipeline: Get detailed information about a specific pipeline
    • Required: project_id, pipeline_id
  • create_pipeline: Create a new pipeline
    • Required: project_id, ref (branch or tag)
    • Optional: variables (array of key-value pairs)
  • retry_pipeline: Retry a failed pipeline
    • Required: project_id, pipeline_id
  • cancel_pipeline: Cancel a running pipeline
    • Required: project_id, pipeline_id
  • delete_pipeline: Delete a pipeline
    • Required: project_id, pipeline_id
  • list_pipeline_jobs: List jobs within a pipeline
    • Required: project_id, pipeline_id
    • Optional: scope (filter by job status), include_retried
  • get_pipeline_variables: Get variables used in a pipeline
    • Required: project_id, pipeline_id
  • get_job_logs: Get the log (trace) file of a specific job
    • Required: project_id, job_id
  • get_job_trace: Get job trace with advanced options for large logs
    • Required: project_id, job_id
    • Optional: lines_limit (default: 1000), tail (default: false), raw (default: false)

User Information

  • get_user: Get current authenticated user information

Example Usage

Once configured with Claude Desktop, you can use natural language to interact with GitLab:

  • "List my GitLab projects"
  • "Show me open issues in project mygroup/myproject"
  • "Create a new issue titled 'Bug fix needed' in project 123"
  • "List merge requests for the main branch"
  • "Get details of merge request #42 in myproject"
  • "Show me all pipelines in project 123"
  • "Get the status of pipeline #456 in myproject"
  • "Create a new pipeline for the main branch"
  • "Retry the failed pipeline #789"
  • "Cancel the running pipeline #101"
  • "Show me all jobs in pipeline #456"
  • "Get the logs for job #789 in project myproject"
  • "Get the last 500 lines of logs for job #789"
  • "Show me the first 100 lines of job trace for debugging"

Enhanced Job Trace Features

The get_job_trace tool provides advanced options for handling large CI/CD job logs:

Key Features

  • 🔢 Line Limiting: Control how many lines to retrieve (default: 1000)
  • 🔚 Tail Mode: Get the last N lines instead of first N lines
  • 📄 Raw Mode: Return clean log content without formatting
  • 📊 Metadata: Shows total lines, truncation info, and navigation hints
  • ⚠️ Large Log Handling: Automatic truncation warnings for logs > limit

Usage Examples

Get last 500 lines (tail mode):

"Get the last 500 lines from job 123 in project myproject"

Get first 100 lines for debugging:

"Show me first 100 lines of job 456 logs"

Raw output without formatting:

"Get raw job logs for job 789 without metadata"

When to Use Each Tool

  • get_job_logs: For complete logs of small to medium jobs
  • get_job_trace: For large logs where you need:
    • Only recent output (tail mode)
    • Quick debugging (line limits)
    • Clean output for scripts (raw mode)
    • Metadata about log size

TypeScript Usage

This package provides complete TypeScript support with comprehensive type definitions:

// Import the server class and types import { GitLabMCPServer } from '@alosies/gitlab-mcp-server'; import type { GitLabProject, GitLabIssue, GitLabJob, ListProjectsParams, GetJobLogsParams, GetJobTraceParams } from '@alosies/gitlab-mcp-server/types'; // Use typed parameters const projectParams: ListProjectsParams = { search: 'my-project', visibility: 'private', per_page: 10 }; const jobLogsParams: GetJobLogsParams = { project_id: '123', job_id: 456 }; const jobTraceParams: GetJobTraceParams = { project_id: '123', job_id: 456, lines_limit: 500, tail: true, raw: false }; // Type-safe functions function processProject(project: GitLabProject): string { return `Project: ${project.name} (${project.visibility})`; } function processJob(job: GitLabJob): string { return `Job: ${job.name} - Status: ${job.status}`; }

Available Type Categories

  • API Objects: GitLabProject, GitLabIssue, GitLabMergeRequest, GitLabPipeline, GitLabJob, etc.
  • Parameter Types: ListProjectsParams, CreateIssueParams, GetJobLogsParams, etc.
  • Response Types: MCPResponse for all tool responses
  • Server Interface: IGitLabMCPServer for the main server class

API Configuration

By default, the server connects to GitLab.com. To use with a self-hosted GitLab instance, modify the baseUrl in the GitLabConfig interface in src/index.ts:

this.config = { baseUrl: 'https://your-gitlab-instance.com', // Change this token: process.env.NPM_CONFIG_TOKEN || '', };

Error Handling

The server includes comprehensive error handling for:

  • Missing authentication tokens
  • Invalid project IDs or paths
  • API rate limits
  • Network errors
  • Invalid parameters

Errors are returned in a user-friendly format through the MCP protocol.

Development

Project Structure

gitlab-mcp-server/ ├── src/ │ └── index.ts # Main server implementation ├── dist/ # Compiled JavaScript (generated) ├── package.json # Dependencies and scripts ├── tsconfig.json # TypeScript configuration └── README.md # This file

Building

npm run build

Development Mode

npm run dev

This will watch for changes and automatically rebuild the TypeScript code.

License

MIT License

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

Support

For issues and questions:

  1. Check the GitLab API documentation: https://docs.gitlab.com/ee/api/
  2. Review the MCP specification: https://modelcontextprotocol.io/
  3. Create an issue in this repository

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

A TypeScript MCP server that provides integration with GitLab's REST API, allowing users to interact with GitLab projects, issues, merge requests, pipelines, and more through natural language.

  1. Features
    1. Prerequisites
      1. Installation
        1. Option 1: Use with npx (Recommended)
        2. Option 2: Global Installation
        3. Option 3: Development from Source
      2. Configuration
        1. Creating a GitLab Personal Access Token
        2. Environment Setup
      3. Usage
        1. Running the Server
        2. Configuring with Claude Desktop
      4. Available Tools
        1. Project Management
        2. Issue Management
        3. Merge Request Management
        4. Repository Operations
        5. Pipeline Management
        6. User Information
      5. Example Usage
        1. Enhanced Job Trace Features
          1. Key Features
          2. Usage Examples
          3. When to Use Each Tool
        2. TypeScript Usage
          1. Available Type Categories
        3. API Configuration
          1. Error Handling
            1. Development
              1. Project Structure
              2. Building
              3. Development Mode
            2. License
              1. Contributing
                1. Support

                  Related MCP Servers

                  • https://github.com/owayo/gitlab-mcp-server

                    owayo
                    -
                    security
                    A
                    license
                    -
                    quality
                    GitLabとの連携機能を提供するModel Context Protocol (MCP) サーバーです。GitLabの特定のプロジェクトからパイプラインの失敗情報やマージリクエストへの指摘事項を取得し、AIアシスタントに提供します。
                    Last updated -
                    Python
                    MIT License

                  • GitLab MCP Server

                    harshmaur
                    -
                    security
                    F
                    license
                    -
                    quality
                    An MCP server that enables communication with GitLab repositories, allowing interaction with GitLab's API to manage projects, issues, and repositories through natural language.
                    Last updated -
                    20
                    1
                    JavaScript
                    MIT License

                  • GitLab MCP Server

                    rifqi96
                    A
                    security
                    A
                    license
                    A
                    quality
                    A Model Context Protocol server that enables interaction with GitLab accounts to manage repositories, merge requests, code reviews, and CI/CD pipelines through natural language.
                    Last updated -
                    41
                    2
                    TypeScript
                    MIT License
                    • Apple

                  • mcp-server-gitlab

                    ZephyrDeng
                    A
                    security
                    A
                    license
                    A
                    quality
                    基于MCP框架构建的GitLab集成服务器，提供多种GitLab RESTful API工具，支持项目搜索、任务管理、合并请求创建与审核等功能，帮助开发团队高效协作。
                    Last updated -
                    8
                    67
                    2
                    TypeScript
                    MIT License

                  View all related MCP servers

                  New MCP Servers

                  MCP directory API

                  We provide all the information about MCP servers via our MCP API.

                  curl -X GET 'https://glama.ai/api/mcp/v1/servers/Alosies/gitlab-mcp-server'

                  If you have feedback or need assistance with the MCP directory API, please join our Discord server