gitlab-mcp-server

Nuibia/gitlab-mcp-server

3.3

If you are the rightful owner of gitlab-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

A TypeScript-based Model Context Protocol (MCP) server for querying and managing GitLab projects.

Tools
3
Resources
0
Prompts
0

GitLab MCP 服务器

一个基于 TypeScript 的 Model Context Protocol (MCP) 服务器，用于查询和管理 GitLab 项目。

项目结构

gitlab-mcp-server/
├── README.md
├── docs/
│   ├── index.md                # 文档首页（VitePress）
│   ├── USAGE.md                # 完整使用指南（详细配置）
│   ├── guide/
│   │   ├── quickstart.md       # 快速开始（5分钟入门）
│   │   └── http.md             # HTTP 模式指南
│   ├── reference/
│   │   └── tools.md            # 工具参考
│   ├── recipes/
│   │   └── examples.md         # 常见场景
│   └── contributing/
│       └── coding-rules.md     # 代码规范
├── src/
│   ├── index.ts                # Stdio 服务器入口
│   ├── http-server.ts          # HTTP 服务器入口
│   ├── mcp/
│   │   └── register-tools.ts   # 统一注册工具
│   ├── services/
│   │   ├── gitlab.ts           # GitLab API 封装与错误处理
│   │   ├── config.ts           # 运行时配置
│   │   └── index.ts
│   ├── utils/
│   │   ├── format.ts           # 文本格式化纯函数
│   │   └── index.ts
│   └── types/
│       ├── gitlab.ts
│       ├── config.ts
│       └── index.ts
├── test-http-client.js
├── test-server.js
├── package.json
├── tsconfig.json
└── yarn.lock

技术栈

  • TypeScript 5 - 类型安全的开发体验
  • MCP 官方 SDK - Model Context Protocol 实现
  • Express - HTTP 服务器框架
  • Axios - HTTP 客户端
  • Zod - 运行时类型验证

功能特性

  • 🔍 项目列表: 获取 GitLab 实例中的所有项目
  • 🌿 按分支名搜索项目: 支持模糊匹配（不区分大小写）
  • 🧭 按项目名搜索: 支持精确与模糊匹配
  • 🧩 模块化设计: services 负责请求，utils 负责纯数据处理
  • 🔒 自签名证书: 默认忽略 SSL 校验，便于内网/自签名环境接入
  • 🌐 HTTP 模式: 提供 HTTP 传输，适配更多客户端

安装与环境变量

  1. 安装依赖
yarn install
  1. 设置环境变量（至少需要 GITLAB_TOKEN）
# zsh/bash 示例（当前会话生效）
export GITLAB_TOKEN=glpat_xxx
export GITLAB_URL=https://gitlab.com/
export PORT=3000

# 或命令前缀方式
GITLAB_TOKEN=glpat_xxx yarn dev

获取令牌：登录 GitLab → Settings → Access Tokens，勾选 read_api 权限。

启动方式

# 开发（Stdio）
yarn dev

# 生产（Stdio，需要先构建）
yarn build && yarn start

# 开发（HTTP）
yarn http:dev

# 生产（HTTP，需要先构建）
yarn build && yarn http

已注册工具

list_projects

获取当前GitLab实例中所有可访问的项目列表。返回项目的完整信息：项目名称、命名空间、描述、可见性、默认分支、统计信息（星标数、Fork数）以及最后更新时间。项目按更新时间倒序排列，最多返回100个项目。

参数: 无

list_projects_with_branch

搜索包含指定分支名的GitLab项目。不区分大小写，支持模糊匹配。返回匹配的项目及其分支详细信息，包括分支状态（默认分支/保护分支/活跃分支/已合并）、最新提交信息（提交SHA、提交标题、作者、时间）等。

参数: { branchName: string } - 要搜索的分支名，支持模糊匹配

get_project_by_name

通过项目名称或命名空间搜索GitLab项目。支持精确匹配和模糊搜索。返回匹配的项目详细信息，包括项目URL、创建时间、统计信息等。如果未找到匹配项目，会提供搜索建议。

参数: { projectName: string } - 项目名称或命名空间，支持精确和模糊匹配

📖 用户指南

如果你是最终用户，需要配置和使用这个MCP服务器：

  • 🚀 快速开始:
  • 🔧 详细配置:

使用方式

本项目支持两种 MCP 使用方式：

  • Stdio模式：适合本地开发，直接与Cursor集成，无需手动启动服务器
  • HTTP模式：适合内网环境、自签名证书环境，或需要跨进程通信的场景

📖 快速开始：
🔧 完整配置：

故障排除

  • 启动即退出，提示需设置 token：请设置 GITLAB_TOKEN 环境变量
  • 401 Unauthorized：检查 token 是否正确且具备 read_api 权限
  • 403 Forbidden：当前 token 或用户无访问项目权限
  • 404 Not Found：检查 GITLAB_URL 是否正确、版本是否支持 v4 API
  • 网络错误（ECONNREFUSED/ENOTFOUND）：检查网络、地址、VPN 等

开发约定

  • services/ 存放请求和副作用逻辑
  • utils/ 存放纯函数和数据处理逻辑
  • 详细规范请参考 docs/contributing/coding-rules.md

许可证与贡献

  • 许可证: MIT
  • 欢迎贡献: 通过 Issue/PR 参与改进
  • 贡献前请阅读: docs/contributing/coding-rules.md

相关链接