@zephyr-mcp/gitlab-restful-api

An integration server built on the Model Context Protocol (MCP) framework, providing powerful integration capabilities with GitLab instances. This service can be used as a plugin for large language models like Claude, allowing the model to securely access GitLab resources via RESTful APIs.

Features

• GitLab RESTful API Integration: Seamless access to any GitLab instance's API, supporting rich querying and operational capabilities
• Intelligent Field Mapping: Automatically maps simple field names to actual nested paths, lowering the barrier to use
• Field Filtering System: Precise control over returned data fields, reducing unnecessary data transmission
• Multiple Operation Support: Offers various integration operations such as user task queries, project searches, and merge request management
• Smithery Compatible: Fully compatible with Smithery deployment and distribution standards

Quick Start

bash

Install dependencies

npm install

Build the project

npm run build

Start the service

npm run start

Environment Variable Configuration

The service requires the following environment variables:

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

Tool Description

GitlabRestfulApiTool

The GitLab RESTful API tool allows LLMs to perform various GitLab operations, including querying user tasks, searching users and projects, managing merge requests, etc. The tool supports intelligent field mapping and field filtering features, greatly simplifying API operations.

Field Mapping System

The tool provides an intelligent field mapping system that makes it easy to get data without needing to understand the internal structure of the API response:

• Basic fields like id, name are automatically mapped to the corresponding object fields
• Special array representations like project_names can fetch the name field of all elements in the array
• A field guessing mechanism will attempt to infer possible paths if no mapping is found

Supported Operations

The tool supports the following main operation types:

1. getCurrentUserTasks: Get the current user's tasks (merge requests, pending review requests, issues, etc.)
2. searchUserWithProjects: Search for users and their active projects
3. searchProjectWithDetails: Search for projects and get detailed information
4. createMRComment: Add a comment to a merge request
5. acceptMR: Accept and merge a specified merge request
6. raw: A fallback option for direct access to GitLab API endpoints

Usage Examples

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

// Search for users and their projects
await mcp.runTool("gitlab_restful_api", {
operation: "searchUserWithProjects",
username: "Zhang San",
fields: ["id", "name", "username", "project_names"]
});

// Search for projects and get details
await mcp.runTool("gitlab_restful_api", {
operation: "searchProjectWithDetails",
projectName: "Frontend Project",
fields: ["id", "name", "description", "branch_names", "member_names"]
});

// Create a merge request comment
await mcp.runTool("gitlab_restful_api", {
operation: "createMRComment",
projectId: "group/project-name",
mergeRequestId: 123,
comment: "The code looks good, approved!",
fields: ["id", "body", "created_at"]
});

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

Project Structure

gitlab-restful-api/
├── src/
│ ├── tools/
│ │ └── GitlabRestfulApiTool.ts # GitLab RESTful API tool
│ └── index.ts # Server entry point
├── smithery.json # Smithery configuration
├── USAGE.md # Usage documentation
├── package.json
└── tsconfig.json

Using in Claude Desktop Client

NPM Installation

After installation, add the following configuration to the Claude desktop client configuration file:

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

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

Smithery Installation

If you are using Smithery, you can install it directly with the following command:

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

Then, enable this tool in your Smithery configuration.

Learn More

• MCP Framework Documentation
• Smithery Documentation
• GitLab API Documentation