AI导哈

GitLab MCP 服务器

GitLab MCP 服务器是一个基于 TypeScript 实现的 Model Context Protocol (MCP) 服务器，提供 GitLab REST API 的子集作为可调用工具，适用于开发效率提升和项目管理。

  • by anarsyakir
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 anarsyakir/gitlab-mcp

使用说明

GitLab MCP 服务器

这个仓库包含了一个模型上下文协议（MCP）服务器的实现，该服务器暴露了（或提供了）协议的一个子集 GitLab REST API 作为可调用的工具。它使用官方的MCP SDK用TypeScript实现，并通过标准输入/输出运行，因此易于与任何支持MCP的主机集成（例如， 《Codex》（拉丁语，意为“法典”或“典籍”））。

特点/特性

该服务器封装了几个常见的GitLab操作：

  • listProjects — 列出认证用户可见的项目，支持可选的搜索和过滤功能。
  • getProject — 通过项目ID或命名空间路径检索单个项目的详细信息。
  • createProject — 创建一个新项目；支持可选功能 namespaceId， description 并且 visibility。
  • listGroupProjects — 列出属于特定组的项目。
  • listIssues — 列出特定项目的问题。
  • createIssue — 在项目中创建一个问题，包含标题、可选描述、标签和负责人。
  • listBranches — 列出项目中的分支及其提交元数据。
  • createBranch — 从现有分支或提交SHA创建一个新分支。

问题管理

新版本中的新增内容 0.2.0 此服务器提供了用于更全面管理问题的工具：

  • getIssue — 通过提供项目ID和问题的内部ID（IID），检索单个问题的详细信息。
  • updateIssue — 更新现有问题。您可以修改标题、描述、标签，分配用户，更改截止日期或关闭/重新打开问题，使用[stateEvent参数【925839063033099†L1419-L1455】。
  • deleteIssue — 删除一个问题（需要项目所有者或管理员权限）【925839063033099†L1595-L1616】。
  • listIssueNotes — 列出与某个问题相关的评论（备注）。支持排序和过滤选项【817593036777657†L88-L106】。
  • createIssueNote — 在问题【817593036777657†L184-L209】中添加一条新评论。
  • updateIssueNote — 修改关于某一问题的现有备注【817593036777657†L210-L225】。
  • deleteIssueNote — 从问题中删除一条备注【817593036777657†L232-L248】。

每个工具都使用其（特定的）方法来验证其输入 zod 在进行API调用之前。结果以JSON字符串的形式返回，以便您的主机轻松使用。

配置

复制 .env.example 到；对于；向；给；在……方面 .env 并提供您自己的设置：

# Base URL for the GitLab API. Defaults to the public GitLab instance.
GITLAB_BASE_URL=https://gitlab.com/api/v4

# Personal access token with appropriate scopes (for example, `api`).
GITLAB_TOKEN=your_private_token

服务器在启动时读取这些环境变量。如果您省略 GITLAB_TOKEN调用私有资源将会失败。

发展

安装依赖项并以开发模式运行：

npm install
npm run dev

这将以监视模式启动MCP服务器，使用 tsx它从标准输入读取数据，并将数据写入标准输出。要为生产环境构建项目，请运行：

npm run build

然后，您可以使用以下命令启动编译后的服务器：

node dist/server.js

Docker

在容器中构建并运行服务器：

# 1) Build the image
docker build -t gitlab-mcp .

# 2) Run the container with your environment variables
docker run -it --rm \
  -e GITLAB_BASE_URL=https://gitlab.com/api/v4 \
  -e GITLAB_TOKEN=<your_token> \
  gitlab-mcp

或者，使用 docker-compose:

cp .env.example .env
# edit .env with your values
docker compose up --build

在VS Code中与Codex集成

构建完这个MCP服务器后，您可以将其集成到您的Codex配置中。假设您已经在机器的某个位置解压了zip存档并安装了 Codex VS Code 扩展：

  1. 确定绝对路径到 dist/server.js 在这个项目中。
  2. 打开你的Codex设置（~/.codex/config.toml 或者通过Codex设置图形用户界面进行。
  3. 在（某个位置/列表中）添加一个服务器定义 [mcp_servers] 表格：
[mcp_servers.gitlab]
command = "/usr/bin/node"
args = ["/absolute/path/to/gitlab-mcp/dist/server.js"]
[mcp_servers.gitlab.env]
GITLAB_BASE_URL = "https://gitlab.com/api/v4"
GITLAB_TOKEN = "<your_token>"

# optional: enable RMCP client implementation
experimental_use_rmcp_client = true
  1. 重新加载索引（或“知识库”）。你应该能看到 listProjects， getProject， createProject等，这些都可以作为您聊天中的工具使用。

示例工具调用

  • 列出你的项目：

    使用来自MCP主机的工具： listProjects {} 或者添加一个搜索词： listProjects { "search": "my-repo" }。

  • 创建一个项目：

    createProject {
  "name": "my-cool-project",
  "namespaceId": "12345",   // optional, numeric ID or path
  "description": "Project created via MCP",
  "visibility": "private"
}

  • 列出项目的问题：

    listIssues { "projectId": "my-group/my-project" }

  • 创建一个问题：

    createIssue {
  "projectId": "my-group/my-project",
  "title": "Bug: cannot login",
  "description": "Steps to reproduce...",
  "labels": "bug,urgent"
}

  • 创建一个分支：

    createBranch {
  "projectId": "my-group/my-project",
  "branch": "feature/new-api",
  "ref": "main"
}

  • 获取单期杂志：

    getIssue {
  "projectId": "my-group/my-project",
  "issueIid": 42
}

  • 更新一个问题（例如，添加标签并关闭它）：

    updateIssue {
  "projectId": "my-group/my-project",
  "issueIid": 42,
  "addLabels": "frontend,urgent",
  "stateEvent": "close"
}

  • 删除一个问题：

    deleteIssue { "projectId": "my-group/my-project", "issueIid": 42 }

  • 对问题添加评论：

    createIssueNote {
  "projectId": "my-group/my-project",
  "issueIid": 42,
  "body": "We are investigating this bug."
}

  • 列出关于某个问题的评论：

    listIssueNotes { "projectId": "my-group/my-project", "issueIid": 42 }

  • 更新一条评论：

    updateIssueNote {
  "projectId": "my-group/my-project",
  "issueIid": 42,
  "noteId": 123,
  "body": "Updated comment text"
}

  • 删除一条评论：

    deleteIssueNote {
  "projectId": "my-group/my-project",
  "issueIid": 42,
  "noteId": 123
}

请随意扩展 src/gitlab.ts 并且 src/server.ts 包含合并请求、流水线或用户等额外端点。请参阅官方GitLab API文档【333395904541159†L254-L306】以获取指导，并相应地调整输入模式。

相关 MCP