GitLab MCP Server

一个基于 Model Context Protocol (MCP) 的 GitLab 服务器实现，将 GitLab REST API v4 封装为 AI 可调用的工具。

📋 目录

• 项目概述
• 功能特性
• 快速开始
• 使用示例
• 项目结构
• API 参考
• MCP SDK 文档
• 常见问题
• 贡献指南
• 许可证

项目概述

本项目是一个完整的 MCP (Model Context Protocol) 服务器实现，允许 AI 助手（如 Claude Desktop、Cursor 等）直接调用 GitLab API 进行仓库管理、项目操作等任务。

核心功能

• 🤖 AI 集成：无缝集成支持 MCP 协议的 AI 助手
• 📦 仓库管理：创建、查看、删除 GitLab 仓库
• 🌿 分支操作：创建和管理代码分支
• 👤 用户信息：获取当前用户详细信息
• 🔐 安全认证：使用 GitLab Personal Access Token

快速开始

前置要求

• Node.js 18.0 或更高版本
• npm 或 yarn 包管理器
• GitLab Personal Access Token（需具备 api 权限）

安装步骤

1. 克隆或下载项目

git clone <repository-url>
cd gitlab-mcp-server

2. 安装依赖

npm install

3. 配置环境变量

复制环境变量模板并配置：

cp .env.example .env

编辑 .env 文件：

# GitLab Personal Access Token（必填）
GITLAB_TOKEN=你的GitLab访问令牌

# GitLab 实例地址（可选，默认使用 gitlab.com）
GITLAB_HOST=https://gitlab.com

4. 启动服务器

npm start

在 AI 客户端中配置

Claude Desktop 配置

编辑 claude_desktop_config.json：

{
  "mcpServers": {
    "gitlab": {
      "command": "node",
      "args": ["/path/to/gitlab-mcp-server/src/index.js"],
      "env": {
        "GITLAB_TOKEN": "你的GitLab访问令牌"
      }
    }
  }
}

使用示例

创建仓库

// 可用工具: create_gitlab_repository
// 参数: name (必填), description (可选), visibility (可选)

示例对话：

• "在 GitLab 创建一个名为 my-project 的私有仓库"
• "创建一个公开仓库 test-repo，描述为测试项目"

列出项目

// 可用工具: list_gitlab_projects
// 参数: per_page (可选), page (可选), visibility (可选)

示例对话：

• "列出我所有的 GitLab 项目"
• "查看前10个公开项目"

获取项目详情

// 可用工具: get_gitlab_project
// 参数: project_id (必填)

示例对话：

• "查看项目 ID 为 123 的详细信息"
• "获取 username/project-name 项目详情"

创建分支

// 可用工具: create_gitlab_branch
// 参数: project_id (必填), branch_name (必填), ref (可选)

示例对话：

• "在项目 my-project 中创建名为 feature/new-feature 的分支"
• "从 main 分支创建开发分支 dev"

删除项目

// 可用工具: delete_gitlab_project
// 参数: project_id (必填)

⚠️ 注意：此操作不可逆！

获取用户信息

// 可用工具: get_gitlab_user
// 参数: 无

项目结构

gitlab-mcp-server/
├── .env.example              # 环境变量模板
├── package.json              # 项目配置
├── README.md                 # 项目说明文档
├── docs/
│   └── README.md            # MCP SDK 文档（从 unpkg.com 下载）
└── src/
    ├── index.js             # MCP 服务器主入口
    └── gitlab-service.js    # GitLab API 服务封装

API 参考

工具列表

工具名称	描述	必需参数	可选参数
create_gitlab_repository	创建新的 GitLab 仓库	name	description, visibility, initialize_with_readme
list_gitlab_projects	获取项目列表	无	per_page, page, visibility
get_gitlab_project	获取项目详情	project_id	无
delete_gitlab_project	删除项目	project_id	无
create_gitlab_branch	创建分支	project_id, branch_name	ref
get_gitlab_user	获取当前用户信息	无	无

环境变量

变量名	必填	描述	默认值
GITLAB_TOKEN	是	GitLab Personal Access Token	无
GITLAB_HOST	否	GitLab 实例地址	https://gitlab.com

MCP SDK 文档

本项目使用 @modelcontextprotocol/sdk v1.25.1。完整文档已下载到 docs/README.md。

核心概念

服务器和传输层

MCP 服务器通过传输层与客户端通信。本项目使用 Stdio 传输方式（标准输入输出），适用于本地进程集成。

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

工具 (Tools)

工具允许 AI 调用服务器执行操作：

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  // 处理工具调用
});

资源 (Resources)

资源用于暴露只读数据：

// 注册资源处理器
server.setRequestHandler(ListResourcesRequestSchema, async () => {
  // 返回可用资源列表
});

提示符 (Prompts)

提示符是可复用的模板：

// 注册提示符
server.setRequestHandler(ListPromptsRequestSchema, async () => {
  // 返回可用提示符列表
});

官方资源

• MCP 官方文档
• MCP 规范
• MCP 示例服务器

常见问题

Q1: GitLab Token 需要什么权限？

需要至少 api 权限才能创建仓库。如需只读操作，可使用 read_api 权限。

Q2: 支持自托管 GitLab 吗？

支持。设置 GITLAB_HOST 环境变量指向你的 GitLab 实例即可。

Q3: 如何调试？

服务器日志会输出到 stderr，因为 stdout 用于 MCP 协议通信：

npm start 2> debug.log

Q4: 遇到权限错误怎么办？

# 确保 .env 文件中的 token 正确
cat .env

# 验证 token 是否有效
curl -H "PRIVATE-TOKEN: $GITLAB_TOKEN" https://gitlab.com/api/v4/user

Q5: 支持 Windows 吗？

本项目是跨平台的，但在 Windows 上可能需要调整传输层配置。推荐使用 WSL 或 Docker 运行。

贡献指南

欢迎贡献代码！请遵循以下步骤：

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 创建 Pull Request

许可证

本项目基于 MIT 许可证开源。

致谢

• Model Context Protocol - AI 上下文交互协议
• GitLab - 代码托管和 CI/CD 平台
• @modelcontextprotocol/sdk - MCP TypeScript SDK