GitLab连接工具（futuramacoder） - MCP Server 功能介绍与安装配置

Name: GitLab连接工具
Author: futuramacoder

使用说明

gitlab mcp

用Go编写的只读MCP（模型上下文协议）服务器，用于连接 克劳德代码 到自托管的GitLab实例。它使Claude可以直接访问内部库源代码、文档和示例，因此您可以提出以下问题 “使用Y库构建X” 针对没有公开文档的私有repo。

服务器通过以下方式在本地运行标准传输并公开了五个可组合的工具，Claude将这些工具链接在一起，以发现库、浏览文件树和读取源文件。

先决条件

转到1.23+ 已安装(下载)
A. 自托管GitLab 实例（或gitlab.com）
A. GitLab个人访问令牌 随着 read_api 范围
克劳德代码CLI 已安装（ claude 命令必须在您的终端中可用）。看 Claude代码文档有关安装说明。

安装

选项A：安装 `go install`

go install github.com/futuramacoder/gitlab-mcp/cmd/gitlab-mcp@latest

这个地方 gitlab-mcp 二进制在你的 $GOPATH/bin （或 $HOME/go/bin 默认情况下）。确保该目录位于您的 PATH.

选项B：从源代码构建

git clone https://github.com/futuramacoder/gitlab-mcp.git
cd gitlab-mcp
go build -o gitlab-mcp ./cmd/gitlab-mcp

可选地将二进制文件移动到您的 PATH:

sudo mv gitlab-mcp /usr/local/bin/

验证安装

gitlab-mcp --version

您应该看到如下输出：

gitlab-mcp dev

配置

服务器从YAML文件读取其配置。查找顺序为：

--config CLI标志（如果提供）
GITLAB_MCP_CONFIG 环境变量（如果设置）
~/.config/gitlab-mcp/config.yaml （默认）

创建配置文件

mkdir -p ~/.config/gitlab-mcp

最小配置

创建 ~/.config/gitlab-mcp/config.yaml 内容如下：

gitlab:
  url: "https://gitlab.internal.company.com"
  token: "${GITLAB_TOKEN}"

这 ${GITLAB_TOKEN} 语法告诉服务器从 GITLAB_TOKEN 环境变量。请确保将其导出到您的shell中：

export GITLAB_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx"

或者，您可以直接内联令牌（不建议用于共享计算机）：

gitlab:
  url: "https://gitlab.internal.company.com"
  token: "glpat-xxxxxxxxxxxxxxxxxxxx"

完整配置示例

# ~/.config/gitlab-mcp/config.yaml

# GitLab connection
gitlab:
  url: "https://gitlab.internal.company.com"
  token: "${GITLAB_TOKEN}"

# Shared team config (optional)
shared_config:
  project: "devtools/gitlab-mcp-config"
  file_path: "config.yaml"
  ref: "main"

# Logging
log:
  level: "info"   # error | warn | info | debug

# Global defaults
defaults:
  ref_strategy: "latest_tag"    # latest_tag | default_branch
  max_file_size_kb: 100
  max_tree_depth: 10

# Sensitive file filtering (additional patterns)
sensitive_files:
  extra_patterns:
    - "**/*.tfstate"
    - "**/internal-secrets/**"

# Library registry
libraries:
  - alias: "auth-sdk"
    project: "platform/auth-sdk"
    description: "Internal OAuth2/OIDC SDK"
    include:
      - "src/**"
      - "docs/**"
      - "examples/**"
      - "README.md"
    exclude:
      - "**/*_test.go"
      - "testdata/**"

  - alias: "go-utils"
    project: "platform/monorepo"
    root_path: "packages/go-utils"
    description: "Shared Go utility functions"

看规格.md 以获取完整的配置参考。

使用克劳德代码注册

安装二进制文件并创建配置文件后，注册 gitlab-mcp 作为Claude Code中的MCP服务器。选择以下方法之一。

方法1： `claude mcp add-json` （推荐）

这是克劳德代码版本中最可靠的方法。

仅适用于当前项目（本地范围，默认）：

claude mcp add-json gitlab-mcp '{"type":"stdio","command":"gitlab-mcp","args":[],"env":{"GITLAB_TOKEN":"glpat-xxxxxxxxxxxxxxxxxxxx"}}'

对于您的所有项目（用户范围）：

claude mcp add-json --scope user gitlab-mcp '{"type":"stdio","command":"gitlab-mcp","args":[],"env":{"GITLAB_TOKEN":"glpat-xxxxxxxxxxxxxxxxxxxx"}}'

使用自定义配置路径：

claude mcp add-json --scope user gitlab-mcp '{"type":"stdio","command":"gitlab-mcp","args":["--config","/path/to/config.yaml"],"env":{"GITLAB_TOKEN":"glpat-xxxxxxxxxxxxxxxxxxxx"}}'

方法2： `claude mcp add`

claude mcp add --transport stdio --env GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx gitlab-mcp -- gitlab-mcp

添加 --scope user 使其可用于所有项目：

claude mcp add --transport stdio --scope user --env GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx gitlab-mcp -- gitlab-mcp

注：所有选项(--transport, --env, --scope)一定要来之前服务器名称。这 -- 将服务器名称与命令及其参数分开。如果你遇到 missing required argument 'commandOrUrl' 错误，使用方法1(add-json)或者改为方法3（直接配置编辑）。

方法3：编辑 `~/.claude.json` 直接

如果CLI命令不适用于您的版本，您可以直接将服务器配置添加到 ~/.claude.json:

# Open the config file (create it if it doesn't exist)
nano ~/.claude.json

将以下内容添加或合并到JSON文件中：

{
  "mcpServers": {
    "gitlab-mcp": {
      "type": "stdio",
      "command": "gitlab-mcp",
      "args": [],
      "env": {
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

保存文件并重新启动Claude Code。

方法4：项目 `.mcp.json` 用于团队共享

要与您的团队共享MCP服务器配置，请创建 .mcp.json 项目根目录中的文件。此文件应提交到版本控制。

{
  "mcpServers": {
    "gitlab-mcp": {
      "type": "stdio",
      "command": "gitlab-mcp",
      "args": [],
      "env": {
        "GITLAB_TOKEN": "${GITLAB_TOKEN}"
      }
    }
  }
}

每个团队成员都有自己的 GITLAB_TOKEN 环境变量。这 ${GITLAB_TOKEN} 语法在运行时由Claude Code扩展。

您还可以通过CLI添加此内容：

claude mcp add-json --scope project gitlab-mcp '{"type":"stdio","command":"gitlab-mcp","args":[],"env":{"GITLAB_TOKEN":"${GITLAB_TOKEN}"}}'

验证设置

步骤1：检查服务器是否已注册

claude mcp list

你应该看看 gitlab-mcp 在输出中显示其传输类型和命令。

步骤2：检查Claude Code中的服务器状态

启动Claude Code并运行斜线命令：

/mcp

这显示了所有连接的MCP服务器及其状态。 gitlab-mcp 应显示为与5个可用工具连接。

步骤3：手动烟雾测试（可选）

您可以通过直接发送JSON-RPC初始化消息来验证服务器是否在没有Claude Code的情况下启动并响应MCP协议：

echo '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1.0"}}}' | gitlab-mcp 2>/dev/null

成功的响应如下：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": {}
    },
    "serverInfo": {
      "name": "gitlab-mcp",
      "version": "dev"
    }
  }
}

如果您看到此响应，则服务器二进制文件正在工作，配置有效。

使用Claude代码进行测试

服务器注册并验证后，打开Claude Code并尝试以下提示，以确认一切都能端到端地正常工作。

测试1：列出可用库

问克劳德：

List all available libraries from GitLab.

幕后发生了什么： 克劳德称 list_libraries 工具。您应该看到在您的 config.yaml.

预期产量： 库别名、项目路径和描述的列表。如果没有配置库，结果将是一个空列表——这仍然是一个成功的响应。

测试2：搜索项目

问克劳德：

Search for GitLab projects matching "auth".

幕后发生了什么： 克劳德称 search_projects 工具与 query: "auth"。这将动态搜索您的GitLab实例。

预期产量： 匹配项目及其路径、描述和元数据的列表。这确认了GitLab API连接和令牌正在工作。

测试3：获取库信息

问克劳德：

Show me the overview and README for the auth-sdk library.

幕后发生了什么： 克劳德打电话来 get_library_info 随着 library: "auth-sdk"服务器解析git ref（最新标签或默认分支），获取项目元数据和README。

预期产量： 项目元数据（描述、解析引用、标签）和README内容。

测试4：浏览文件树

问克劳德：

Show me the file tree for auth-sdk.

幕后发生了什么： 克劳德打电话来 get_file_tree 随着 library: "auth-sdk"服务器返回一个递归目录列表，其中应用了包含/排除过滤器和敏感文件过滤。

预期产量： 包含文件和目录及其类型（文本/二进制）和大小的树。

测试5：读取特定文件

问克劳德：

Read the file src/client.go from auth-sdk.

幕后发生了什么： 克劳德打电话来 read_file 随着 library: "auth-sdk" 和 path: "src/client.go"服务器获取文件内容，将其与敏感文件模式进行核对，并返回解码后的文本。

预期产量： 文件的全文内容。

测试6：完整的工作流程（端到端）

尝试一个将多个工具链接在一起的现实提示：

I need to use the auth-sdk library. Show me what it provides and give me an example of how to use it.

幕后发生了什么： 克劳德通常会：

呼叫 get_library_info 阅读README并了解库
呼叫 get_file_tree 浏览文件结构
呼叫 read_file 在示例文件或关键源文件上了解API

这测试了整个工具链，并确认克劳德可以有效地组合工具。

可用工具

工具	说明
`list_libraries`	列出注册表中的所有库（共享+个人配置）
`search_projects`	在GitLab上搜索不在预配置注册表中的项目
`get_library_info`	获取库的元数据和README
`get_file_tree`	获取库或项目的递归文件树
`read_file`	从库或项目中读取单个文件的内容

看规格.md 第4节了解完整的参数详细信息和响应模式。

故障排除

服务器未出现在 `/mcp`

解决方案： 添加MCP服务器后重新启动Claude Code。Claude Code在启动时加载MCP配置。

# Re-check the server is registered
claude mcp list

# Then restart Claude Code

“连接已关闭”错误

原因： 这 gitlab-mcp 在您的文件中找不到二进制文件 PATH.

解决方案： 验证二进制文件是否可访问：

which gitlab-mcp

如果它没有返回任何内容，请将Go-bin目录添加到PATH中：

export PATH="$HOME/go/bin:$PATH"

将此行添加到您的 ~/.zshrc 或 ~/.bashrc 使其成为永久性的。

或者，在注册时使用二进制文件的完整路径：

claude mcp add --transport stdio --env GITLAB_TOKEN=glpat-xxx gitlab-mcp -- /full/path/to/gitlab-mcp

AUTH_FAILED错误

原因： GitLab令牌无效、过期或丢失 read_api 范围。

解决方案：

在GitLab中生成新的个人访问令牌（设置>访问令牌）。
确保 read_api 范围已选定。
更新环境或配置文件中的令牌。
重新启动克劳德代码。

启动时出现CONFIG_ERROR

原因： 配置文件缺失、包含无效的YAML或引用未设置的环境变量。

解决方案：

检查配置文件是否存在于预期路径中：
```
cat ~/.config/gitlab-mcp/config.yaml
```
验证YAML语法。
确保所有引用的环境变量（如 ${GITLAB_TOKEN})出口。

手动测试服务器：

GITLAB_TOKEN=glpat-xxx gitlab-mcp --version

PROJECT_NOT_FOUND错误

原因： 配置中的项目路径不存在，或者令牌无法访问它。

解决方案：

验证项目路径是否正确（例如。， platform/auth-sdk).
确保您的令牌可以访问该项目。
尝试使用相同的帐户通过GitLab web UI访问该项目。

查看服务器日志

服务器将结构化JSON日志写入 标准错误。要在手动测试时查看日志，请执行以下操作：

echo '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1.0"}}}' | gitlab-mcp

没有 2>/dev/null 重定向后，您将在stderr上看到日志输出。要增加详细程度，请将日志级别设置为 debug 在您的配置中：

log:
  level: "debug"

或者通过环境变量：

GITLAB_MCP_LOG_LEVEL=debug gitlab-mcp

配置参考

字段	类型	默认值	描述
`gitlab.url`	字符串	必需的	GitLab实例URL
`gitlab.token`	string	-	neneneba API令牌（支持 `${VAR}` 插值）
`gitlab.token_file`	string	--	包含令牌的文件的路径
`log.level`	字符串	`"info"`	日志级别： `error`, `warn`, `info`, `debug`
`defaults.ref_strategy`	字符串	`"latest_tag"`	如何解析git refs： `latest_tag` 或 `default_branch`
`defaults.max_file_size_kb`	int	`100`	返回给Claude的最大文件大小（KB）
`defaults.max_tree_depth`	int	`10`	最大目录递归深度
`sensitive_files.extra_patterns`	列表	`[]`	要阻止的其他gitignore样式图案
`libraries`	列表	`[]`	库注册表项
`shared_config.project`	string	--	共享团队配置的GitLab项目路径

看规格.md 对于完整的规范，包括共享配置合并、敏感文件denylist、二进制检测、缓存行为和错误代码。

许可证

有关许可证信息，请参阅存储库。

使用说明

gitlab mcp

先决条件

安装

选项A：安装 go install

选项B：从源代码构建

验证安装

配置

创建配置文件

最小配置

完整配置示例

使用克劳德代码注册

方法1： claude mcp add-json （推荐）

方法2： claude mcp add

方法3：编辑 ~/.claude.json 直接

方法4：项目 .mcp.json 用于团队共享

验证设置

步骤1：检查服务器是否已注册

步骤2：检查Claude Code中的服务器状态

步骤3：手动烟雾测试（可选）

使用Claude代码进行测试

测试1：列出可用库

测试2：搜索项目

测试3：获取库信息

测试4：浏览文件树

测试5：读取特定文件

测试6：完整的工作流程（端到端）

可用工具

故障排除

服务器未出现在 /mcp

“连接已关闭”错误

AUTH_FAILED错误

启动时出现CONFIG_ERROR

PROJECT_NOT_FOUND错误

查看服务器日志

配置参考

许可证

相关 MCP

Figma MCP服务器

Markdown转换服务

MCP 协议测试服务器

图像生成服务

代码安全扫描工具

网页内容抓取服务器

选项A：安装 `go install`

方法1： `claude mcp add-json` （推荐）

方法2： `claude mcp add`

方法3：编辑 `~/.claude.json` 直接

方法4：项目 `.mcp.json` 用于团队共享

服务器未出现在 `/mcp`