Private GitLab MCP Server

A Model Context Protocol (MCP) server for fetching GitLab merge request diffs from your private GitLab instance.

Installation

👉 [Copy and paste it in your browser]

vscode:mcp/install?%7B%22name%22%3A%22privateGitLabMCP%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22%40danielsuri%2Fgitlab-mcp-server%22%5D%2C%22env%22%3A%7B%22GITLAB_URL%22%3A%22%24%7Binput%3Agitlab-url%7D%22%2C%22GITLAB_TOKEN%22%3A%22%24%7Binput%3Agitlab-token%7D%22%2C%22GITLAB_PROJECT_PATH%22%3A%22%24%7Binput%3Agitlab-project-path%7D%22%7D%7D

NPM Package (Recommended)

Install the package using npm:

npm install -g gitlab-mcp-server

The npm package provides:

• ✅ Easy installation: Single npm command
• ✅ Cross-platform: Works on Node.js 14+
• ✅ Automatic updates: Use npm update to get latest version
• ✅ Global CLI: Use gitlab-mcp-server command anywhere

From Source (Development)

For development or if you prefer to build from source:

1. Install Dependencies

First, clone the repository and install the required packages:

git clone https://github.com/Danielsuri/gitlab-mcp-server.git
cd gitlab-mcp-server
npm install

Usage

Using the NPM Package

After installing the npm package globally, you can use the server directly:

# Run the server
gitlab-mcp-server

# Or use it programmatically
node -e "require('gitlab-mcp-server').main()"

2. Configure GitLab Access

You need to set up your GitLab personal access token and URL:

1. Get your GitLab Personal Access Token:

   • Go to your GitLab instance (e.g., https://gitlab.example.com)
   • Navigate to User Settings → Access Tokens
   • Create a new token with read_api scope
   • Copy the generated token

2. Update the configuration:

   • Open mcp.json
   • Replace YOUR_GITLAB_TOKEN_HERE with your actual GitLab token
   • Update the GITLAB_URL if you're using a different GitLab instance (default is https://gitlab.example.com)

3. Configure MCP Client

Add the server configuration to your MCP client (e.g., Claude Desktop):

Copy the contents of mcp.json to your MCP client configuration file.

For Claude Desktop:

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

Make sure to update the cwd path in the configuration to match your actual project directory.

Manual VS Code Installation

If you want to run the server manually in VS Code:

1. Create a .vscode directory in your project and add an mcp.json file inside it.
2. In VS Code, click Add Server, choose npm package, and paste @danielsuri/[email protected].
3. Your .vscode/mcp.json should look like:

{
    "servers": {
        "gitlab-mcp-server": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "@danielsuri/[email protected]"
            ],
            "cwd": "${workspaceFolder}",
            "env": {
                "GITLAB_URL": "https://gitlab.example.com",
                "GITLAB_TOKEN": "YOUR_GITLAB_TOKEN_HERE",
                "GITLAB_PROJECT_PATH": "your-group/your-project"
            }
        }
    },
    "inputs": []
}

4. Replace the GITLAB_URL, GITLAB_TOKEN, and GITLAB_PROJECT_PATH values with your GitLab instance URL, personal access token, and project path.
5. Start the server from the MCP extension.

Available Tools

hello_world

Returns a friendly hello message to test the connection.

fetch_merge_request_diff

Fetches the diff of a GitLab merge request.

Parameters:

• project_path (string): The GitLab project path (e.g., "group/subgroup/project")
• mr_iid (integer): The merge request IID (internal ID)

Example usage:

{
  "project_path": "your-group/your-project",
  "mr_iid": 9045
}

get_merge_request_commentable_lines

Gets a list of lines that can be commented on in a merge request diff. This is useful to identify valid line numbers before adding inline comments.

Parameters:

• project_path (string): The GitLab project path (e.g., "group/subgroup/project")
• mr_iid (integer): The merge request IID (internal ID)

Returns: A list of files with their commentable lines, including:

• type: "new" for added lines, "old" for removed lines
• line_number: The line number in the file
• content: The actual line content

add_merge_request_inline_comment

Adds an inline comment to a specific line in a merge request diff. Only lines that have been changed (added or removed) can be commented on.

Parameters:

• project_path (string): The GitLab project path
• mr_iid (integer): The merge request IID
• file_path (string): Path to the file in the diff
• line_number (integer): Line number to comment on (use get_merge_request_commentable_lines to find valid lines)
• comment_body (string): The comment text
• line_type (string, optional): "new" for added lines or "old" for removed lines (default: "new")

Example usage:

{
  "project_path": "group/project",
  "mr_iid": 123,
  "file_path": "src/main.js",
  "line_number": 15,
  "comment_body": "This function could be optimized",
  "line_type": "new"
}

Testing

You can test the server manually:

# Test hello world
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "hello_world", "arguments": {}}}' | node server.js

# Test merge request diff fetch
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "fetch_merge_request_diff", "arguments": {"project_path": "your/project/path", "mr_iid": 123}}}' | node server.js

# Test getting commentable lines
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_merge_request_commentable_lines", "arguments": {"project_path": "your/project/path", "mr_iid": 123}}}' | node server.js

# Test adding an inline comment (requires valid GitLab credentials)
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "add_merge_request_inline_comment", "arguments": {"project_path": "your/project/path", "mr_iid": 123, "file_path": "src/main.js", "line_number": 15, "comment_body": "Test comment"}}}' | node server.js

Running Unit Tests

# Test basic functionality
npm test

# Test hello world specifically
npm run test-hello

From Source Testing

# Test hello world with test server
echo '{"type":"tools/call","name":"hello_world","params":{}}' | node test-server.js

Development

NPM Scripts

• npm start - Run the main server
• npm test - Run the test server
• npm run test-hello - Test hello world function specifically

Environment Variables

• GITLAB_URL - GitLab instance URL (default: "https://gitlab.example.com")
• GITLAB_TOKEN - GitLab personal access token with read_api scope
• GITLAB_PROJECT_PATH - GitLab project path (default: "your-group/your-project")

Creating Releases

This project uses automated release management. To create a new release:

1. Go to GitHub Actions → "Create Release" workflow
2. Click "Run workflow" and enter the new version (e.g., 1.0.0)
3. The workflow will automatically update all version references and publish to NPM

See RELEASE.md for detailed release process documentation.

Requirements

• Node.js 14.0.0 or higher
• Valid GitLab personal access token with read_api scope
• Network access to your GitLab instance

Dependencies

• axios - HTTP client for GitLab API requests

Troubleshooting

• Connection issues: Make sure you're connected to the VPN if your GitLab instance requires it
• 401 Unauthorized: Check that your GitLab token is valid and has the correct permissions
• 404 Project Not Found: Verify the project path is correct and you have access to the project