npm package: @meepo-ab/gitlab-mcp
Description: GitLab MCP Server - An implementation of the Model Context Protocol for GitLab
Author: Meepo AB
Latest version: 1.1.2

# GitLab MCP Server

The GitLab MCP Server is an implementation of the [Model Context Protocol (MCP)](https://modelcontextprotocol.io) for interacting with GitLab. It enables AI-driven development workflows by allowing Large Language Models (LLMs) to interact with GitLab through MCP, providing programmatic access to GitLab features for AI assistants like Claude.

## Features

This MCP server provides a comprehensive set of tools for interacting with GitLab:

### Merge Request Management
- **Create Merge Requests** - Create new merge requests after local development
- **View Merge Request Details** - Retrieve detailed information about merge requests
- **List Merge Requests** - List and filter merge requests in a project
- **Get File Changes** - Retrieve file changes in a merge request

### Code Review
- **Comment Management** - Add, view, and reply to comments on merge requests
- **Inline Commenting** - Add comments to specific lines of code in merge requests
- **Multi-line Commenting** - Add comments spanning multiple lines of code
- **Discussion Threads** - Manage discussion threads on merge requests
- **Apply Suggested Fixes** - Apply fixes suggested in comments

### Approval Workflow
- **Approve Merge Requests** - Approve merge requests programmatically
- **Resolve Discussions** - Resolve or unresolve discussion threads

### Repository Access
- **File Access** - Retrieve file contents from repositories
- **File Search** - Search for files within a repository
- **Branch Management** - List and manage repository branches

### CI/CD Integration
- **Pipeline Status** - Check the status of CI/CD pipelines
- **Job Logs** - Retrieve logs from CI/CD jobs
- **Pipeline Retry** - Retry failed pipelines

## Configuration

### Prerequisites

- A GitLab account with a Personal Access Token (with `api` scope)
- An MCP client like [Cursor](https://cursor.sh) or [Claude](https://claude.ai)

### Cursor MCP Configuration

To use this MCP server with Cursor, create a `.cursor/mcp.json` file in your project directory with the following configuration:

```json
{
  "mcpServers": {
    "gitlab-mcp": {
      "command": "npx",
      "args": [
        "@meepo-ab/gitlab-mcp"
      ],
      "env": {
        "GITLAB_TOKEN": "your_gitlab_personal_access_token",
        "PROJECT_ID": "your_project_id"
      }
    }
  }
}
```

Replace:
- `your_gitlab_personal_access_token` with your GitLab Personal Access Token
- `your_project_id` with your GitLab project ID (optional)

> **⚠️ SECURITY NOTE**: The `.cursor/mcp.json` file contains sensitive credentials. Make sure to:
> 1. Add `.cursor/mcp.json` to your `.gitignore` file to prevent accidentally committing it
> 2. Never share this file with others
> 3. Use the provided `.cursor/mcp.json.example` file as a template and copy it to `.cursor/mcp.json`

This configuration automatically downloads and runs the latest version of the GitLab MCP Server without requiring any manual installation.

## Usage

The GitLab MCP Server is designed to be used by AI assistants through the Model Context Protocol. It communicates over STDIO by default and is launched by an MCP client like Claude in Cursor.

When interacting with an AI assistant in Cursor, the assistant will have access to the GitLab tools if properly configured, allowing you to:

- Ask for information about merge requests
- Request code reviews
- Add comments to merge requests
- Manage approval workflows
- Access repository files
- Check pipeline status and logs

### Example Workflows

1. **Code Review Workflow**:
   - Request the AI to review a merge request
   - The AI can fetch the MR details, changes, and existing comments
   - The AI can add inline comments with suggestions

2. **Merge Request Creation**:
   - After making local changes, ask the AI to create a merge request
   - The AI can handle the MR creation with appropriate title and description

3. **Pipeline Issue Resolution**:
   - When a pipeline fails, ask the AI to help debug
   - The AI can retrieve job logs and suggest fixes

## Development

If you want to contribute to this project or build it from source:

1. Clone the repository:
```bash
git clone https://gitlab.com/meepoab/ai-labs/mcp-servers/gitlab-mcp.git
cd gitlab-mcp
```

2. Install dependencies:
```bash
npm install
```

3. Build the project:
```bash
npm run build
```

### Available Scripts

- `npm run build` - Build the TypeScript code
- `npm run dev` - Watch for changes and rebuild automatically
- `npm test` - Run tests
- `npm run lint` - Lint the code
- `npm run format` - Format the code with Prettier

### Project Structure

- `src/api` - GitLab API client and related functions
- `src/config` - Configuration management
- `src/resources` - MCP resources for accessing GitLab data
- `src/server` - MCP server implementation
- `src/tools` - MCP tools for interacting with GitLab
- `src/types` - TypeScript type definitions
- `src/utils` - Utility functions
- `src/tests` - Test files

## Roadmap

See [documentation/roadmap.md](documentation/roadmap.md) for the detailed development roadmap.

## License

MIT