MCP server by masx200
GitLab MCP Server
一个基于 Model Context Protocol (MCP) 的 GitLab 服务器实现，将 GitLab REST API v4 封装为 AI 可调用的工具。
📋 目录
项目概述
本项目是一个完整的 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权限）
安装步骤
- 克隆或下载项目
git clone <repository-url>
cd gitlab-mcp-server
- 安装依赖
npm install
- 配置环境变量
复制环境变量模板并配置：
cp .env.example .env
编辑 .env 文件：
# GitLab Personal Access Token（必填）
GITLAB_TOKEN=你的GitLab访问令牌
# GitLab 实例地址（可选，默认使用 gitlab.com）
GITLAB_HOST=https://gitlab.com
- 启动服务器
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 () => {
// 返回可用提示符列表
});
官方资源
常见问题
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 运行。
贡献指南
欢迎贡献代码！请遵循以下步骤：
- Fork 本仓库
- 创建特性分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 创建 Pull Request
许可证
本项目基于 MIT 许可证开源。
致谢
- Model Context Protocol - AI 上下文交互协议
- GitLab - 代码托管和 CI/CD 平台
- @modelcontextprotocol/sdk - MCP TypeScript SDK