GitLab Documentation MCP Server

GitLab 文档 MCP 服务

一个 Model Context Protocol（MCP）服务，可搜索 GitLab 官方文档。此服务为多个 GitLab OSS 仓库中的 Markdown 文档建立索引，并向 AI 助手和其他 MCP 客户端提供访问能力。

功能

• 全文搜索：使用 SQLite FTS5 搜索 GitLab 文档
• 特定版本的文档：可针对任意 GitLab 版本（例如 18.7.2）或最新版本构建
• 为多个仓库建立索引：
  • GitLab CE/EE（主应用）
  • GitLab Runner（CI/CD Runner）
  • Omnibus GitLab（安装包）
  • Gitaly（Git RPC 服务）
  • GitLab Pages（静态网站）
  • GitLab Agent（Kubernetes 集成，包含 KAS）
• 优化的 Docker 镜像：使用稀疏检出和筛选器来尽可能减小体积

构建 Docker 镜像

查找 GitLab 版本

查找所需 GitLab 版本系列的最新补丁版本：

• GitLab 18.7.x 标签
• GitLab 18.6.x 标签
• 所有 GitLab 标签

为特定版本构建

# Set the GitLab version you want (use full patch version)
GITLAB_VERSION=18.7.2

# Build the image
GITLAB_MINOR=$(echo $GITLAB_VERSION | cut -d. -f1,2)
docker build -f docker/Dockerfile --build-arg GITLAB_VERSION=$GITLAB_VERSION \
    -t gitlab-docs-mcp:$GITLAB_VERSION \
    -t mcp/gitlab-docs-mcp:$GITLAB_VERSION \
    -t gitlab-docs-mcp:$GITLAB_MINOR \
    -t mcp/gitlab-docs-mcp:$GITLAB_MINOR .

# Verify the images were created
echo "\nCreated images:"
docker images | grep gitlab-docs-mcp

# Test the image - initialize and list tools
echo "\nTesting MCP server initialization:"
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | \
  docker run -i --rm mcp/gitlab-docs-mcp:$GITLAB_VERSION | jq .

echo "\nListing available tools:"
(echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'; \
 echo '{"jsonrpc":"2.0","id":2,"method":"tools/list"}') | \
  docker run -i --rm mcp/gitlab-docs-mcp:$GITLAB_VERSION 2>/dev/null | tail -1 | jq .

为最新版本（主分支）构建

docker build -f docker/Dockerfile \
    -t gitlab-docs-mcp:latest \
    -t mcp/gitlab-docs-mcp:latest .

# Verify the images were created
echo "\nCreated images:"
docker images | grep gitlab-docs-mcp

# Test the image - initialize and list tools
echo "\nTesting MCP server initialization:"
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | \
  docker run -i --rm mcp/gitlab-docs-mcp:latest | head -20
echo "\nListing available tools:"
(echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'; \
 echo '{"jsonrpc":"2.0","id":2,"method":"tools/list"}') | \
  docker run -i --rm mcp/gitlab-docs-mcp:latest 2>/dev/null | tail -1 | jq .```

## Installation

This server is published to the [MCP Community Registry](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.nunolima/gitlab-docs-mcp).

### Prerequisites

- Docker installed and running
- MCP-compatible client (Claude Desktop, Cline, Cursor, etc.)

### Setup Instructions

#### Claude Desktop

1. **Locate your config file**:
   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
   - Linux: `~/.config/Claude/claude_desktop_config.json`

2. **Add the server configuration**:
   ```json
   {
     "mcpServers": {
       "gitlab-docs": {
         "command": "docker",
         "args": ["run", "-i", "--rm", "nunolima/gitlab-docs-mcp:18.7"]
       }
     }
   }

3. 重启 Claude Desktop：此服务将显示在 MCP 工具菜单中（🔌 图标）

Cline（VS Code 扩展）

1. 在 VS Code 中打开 Cline 设置
2. 转到 MCP Servers 部分
3. 添加此配置：

   {
     "mcpServers": {
       "gitlab-docs": {
         "command": "docker",
         "args": ["run", "-i", "--rm", "nunolima/gitlab-docs-mcp:18.7"]
       }
     }
   }
   

4. 重新加载 VS Code 窗口

Cursor

1. 打开 Cursor 设置
2. 转到 Features → Model Context Protocol
3. 添加服务配置：

   {
     "mcpServers": {
       "gitlab-docs": {
         "command": "docker",
         "args": ["run", "-i", "--rm", "nunolima/gitlab-docs-mcp:18.7"]
       }
     }
   }
   

版本选择

选择与 GitLab 部署相匹配的版本：

// For GitLab 18.7.x
"args": ["run", "-i", "--rm", "nunolima/gitlab-docs-mcp:18.7"]

// For latest GitLab version
"args": ["run", "-i", "--rm", "nunolima/gitlab-docs-mcp:latest"]

验证

设置完成后，验证服务是否正常运行：

1. 在 Claude Desktop 中：查找 🔌 图标，应能看到列出的“gitlab-docs”
2. 测试查询：让 Claude 搜索 GitLab 文档，例如：“搜索 GitLab 文档，查找 CI/CD 流水线配置”
3. 检查 Docker：发出查询后运行 docker ps -a，查看容器是否运行过

一个不错的 AI 请求测试消息是：Using only the "gitlab-docs-mcp" mcp tools as source, what is the latest x.y.z GitLab version covered in the GitLab upgrade notes (doc/update/versions/)?

故障排查

客户端中未显示服务：

• 确保 Docker 正在运行：docker info
• 检查配置文件 JSON 是否有效（没有尾随逗号，使用正确的引号）
• 完全重启 MCP 客户端

“Cannot connect to Docker daemon”错误：

• 启动 Docker Desktop
• 确认 Docker 可访问：docker ps

文档版本过旧：

• 使用其他版本标签（见上文“版本选择”）
• 查看可用标签：https://hub.docker.com/r/nunolima/gitlab-docs-mcp/tags

可用工具

连接后，服务会提供以下工具（MCP Python SDK v2，结构化输出）：

• search_docs：全文搜索所有 GitLab 文档（返回路径、标题和仓库）
• get_doc：根据搜索结果中的准确路径检索指定文档
• search_and_fetch：一次调用即可搜索并返回每个命中项的完整 Markdown

资源

• docs://repos：已建立索引的仓库键
• docs://{+path}：已建立索引的文档路径对应的完整 Markdown

查询示例

可以向 AI 助手提出以下问题：

• “搜索 GitLab 文档，了解如何使用 Docker 设置 GitLab Runner”
• “查找有关 GitLab CI/CD 流水线语法的文档”
• “GitLab 文档对备份和还原有何说明？”
• “搜索 GitLab Pages 自定义域名配置”

工作原理

1. 构建时：使用稀疏检出从 GitLab 仓库克隆文档文件夹
2. 建立索引：解析 Markdown 文件并构建 SQLite FTS5 搜索索引
3. 运行时：MCP 服务提供搜索工具，用于查询已建立索引的文档

版本策略

• 主 GitLab 仓库：使用完整版本标签（例如，v18.7.2-ee）
• Omnibus GitLab：使用带 +ee 后缀的完整版本（例如，18.7.2+ee.0）
• 其他仓库：使用 major.minor.0 版本（例如，v18.7.0）
  • 每个 major.minor 版本使用第一个稳定版本（.0）
  • 示例：构建 GitLab 18.7.2 时，将使用 Runner/Gitaly/Pages/Agent v18.7.0

开发

项目结构

python/gitlab-docs-mcp/
├── docker/
│   └── Dockerfile         # Main Dockerfile with version support
├── indexer/
│   └── build_index.py     # Builds search index from markdown files
├── server/
│   └── main.py           # MCP server implementation
├── data/
│   └── docs.db           # SQLite FTS5 database (generated)
└── repos/                # Cloned documentation (generated)

本地开发

# Install dependencies
pip install -r requirements.txt

# Clone repos manually for testing
# (or let Docker handle it)

# Build index
python indexer/build_index.py

# Run server (stdio)
python -m server.main

集成测试（curl + jq）

test.sh 使用 Streamable HTTP 启动 Docker 镜像，并根据 MCP 协议 2026-07-28 验证 discover、工具和资源：

# Rebuild image first, then:
./test.sh 19.0.5

# Or against an already-running HTTP server:
MCP_TRANSPORT=streamable-http MCP_HOST=0.0.0.0 MCP_PORT=8000 python -m server.main
MCP_BASE_URL=http://127.0.0.1:8000/mcp ./test.sh

许可证

MIT 许可证 - 版权所有 (c) 2026 Nuno Lima

本项目为 GitLab 的开源仓库编制文档索引。各仓库的许可证详情请参阅相应仓库。

致谢

本项目的开发得到了 OLX 的支持，该公司提供了 AI 辅助开发工具的使用权限。