GitLab API MCP server

The GitLab RESTful API MCP server provides integration with GitLab instances, allowing large language models like Claude to securely access GitLab resources through a RESTful API. This server acts as a plugin that enables models to perform various GitLab operations including querying tasks, searching projects, and managing merge requests.

Installation

Prerequisites

Before installing, ensure you have Node.js and npm installed on your system.

Setup Steps

1. Install dependencies:

npm install

2. Build the project:

npm run build

3. Configure environment variables:

GITLAB_API_URL=https://your-gitlab-instance.com  # GitLab instance URL
GITLAB_TOKEN=your_access_token                   # GitLab access token

4. Start the server:

npm run start

Usage

Using with Claude Desktop Client

NPM Installation

After installing the package, add the following configuration to your Claude desktop client config file:

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

{
  "mcpServers": {
    "@zephyr-mcp/gitlab-restful-api": {
      "command": "npx",
      "args": ["-y", "@zephyr-mcp/gitlab-restful-api"]
    }
  }
}

Smithery Installation

If you use Smithery, install with:

smithery install @zephyr-mcp/gitlab-restful-api

Then enable this tool in your Smithery configuration.

GitLab RESTful API Tool

The server provides a tool called gitlab_restful_api that supports various GitLab operations with smart field mapping and filtering capabilities.

Supported Operations

• getCurrentUserTasks: Retrieves the current user's tasks (merge requests, review requests, issues)
• searchUserWithProjects: Searches for users and their active projects
• searchProjectWithDetails: Searches for projects and retrieves detailed information
• createMRComment: Adds comments to merge requests
• acceptMR: Accepts and merges specified merge requests
• raw: Fallback method for direct access to GitLab API endpoints

Field Mapping System

The tool provides an intelligent field mapping system to easily retrieve data without understanding the API response structure:

• Basic fields like id and name are automatically mapped to corresponding object fields
• Special array notations like project_names retrieve the name field from all elements in an array
• Field guessing mechanism attempts to infer possible paths when no mapping is found

Usage Examples

Get Current User Tasks

await mcp.runTool("gitlab_restful_api", {
  operation: "getCurrentUserTasks",
  includeAssignedMRs: "true",
  includeReviewMRs: "true",
  fields: ["id", "name", "username", "assigned_mrs"]
});

Search Users and Their Projects

await mcp.runTool("gitlab_restful_api", {
  operation: "searchUserWithProjects",
  username: "张三",
  fields: ["id", "name", "username", "project_names"]
});

Search Projects with Details

await mcp.runTool("gitlab_restful_api", {
  operation: "searchProjectWithDetails",
  projectName: "前端项目",
  fields: ["id", "name", "description", "branch_names", "member_names"]
});

Create Merge Request Comment

await mcp.runTool("gitlab_restful_api", {
  operation: "createMRComment",
  projectId: "group/project-name",
  mergeRequestId: 123,
  comment: "代码看起来不错，已批准！",
  fields: ["id", "body", "created_at"]
});

Accept Merge Request

await mcp.runTool("gitlab_restful_api", {
  operation: "acceptMR",
  projectId: "group/project-name",
  mergeRequestId: 789,
  mergeOptions: {
    shouldRemoveSourceBranch: true
  },
  fields: ["id", "state", "title"]
});

Additional Resources

• MCP Framework Documentation
• Smithery Documentation
• GitLab API Documentation

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.