GitLab模型上下文协议服务器（CarmeloRicarte） - MCP Server 功能介绍与安装配置

Name: GitLab模型上下文协议服务器
Author: CarmeloRicarte

使用说明

GitLab MCP服务器

用于GitLab与Claude Code和AI助手集成的模型上下文协议（MCP）服务器。

特性

项目：列出并获取项目详细信息
分支：列出并创建分支
问题：创建并列出问题
合并请求：创建并列出MR
文件：读取和写入存储库文件
搜索：在存储库中搜索代码

需求

包子 >= 1.0 或 Node.js >= 18
GitLab个人访问令牌 api 范围

安装

服务器发布在npm上，可以直接运行：

# Using Bun (recommended)
bunx @carmeloricarte/gitlab-mcp-server

# Using Node.js
npx @carmeloricarte/gitlab-mcp-server

无需克隆存储库或手动安装依赖项。

配置

设置以下环境变量：

变量	必填	默认	描述
`GITLAB_TOKEN`	是	-	GitLab个人访问令牌
`GITLAB_HOST`	没有	`https://gitlab.com`	GitLab实例URL

对于具有自签名证书的自托管GitLab：

export NODE_TLS_REJECT_UNAUTHORIZED=0

环境变量设置

配置凭据有两种方法：

选项A：MCP配置中的变量（最简单）

直接在MCP配置中传递所有变量。最容易在新机器上快速设置。

⚠️ 备注：令牌存储在配置文件（本地、私有）中。可供个人使用。

选项B：系统环境变量（更安全）

将敏感令牌保持在系统/用户级别，仅在MCP配置中传递非敏感值。

Windows (PowerShell)

# Set permanently for current user
[Environment]::SetEnvironmentVariable("GITLAB_TOKEN", "glpat-your-token", "User")
[Environment]::SetEnvironmentVariable("GITLAB_HOST", "https://your-gitlab.com", "User")

# Verify
[Environment]::GetEnvironmentVariable("GITLAB_TOKEN", "User")

设置变量后重新启动终端/IDE。

macOS / Linux

# Add to ~/.zshrc (macOS) or ~/.bashrc (Linux)
echo 'export GITLAB_TOKEN="glpat-your-token"' >> ~/.zshrc
echo 'export GITLAB_HOST="https://your-gitlab.com"' >> ~/.zshrc

# Reload
source ~/.zshrc

# Verify
echo $GITLAB_TOKEN

IDE/工具配置

💡 小贴士：使用 bunx 如果您安装了Bun，或者 npx 对于Node.js。两者工作方式相同。

⚠️ 重要: ${VARIABLE} 语法在大多数MCP配置中不起作用——值被视为文字字符串，无法解析。使用选项A（硬编码值）或选项B（服务器从中读取的系统变量 process.env).

⚠️ Windows配置

在Windows上，您必须包装 npx 或 bunx 命令与 cmd /c.使用此格式：

{
  "command": "cmd",
  "args": ["/c", "npx", "-y", "@carmeloricarte/gitlab-mcp-server"]
}

或者与Bun：

{
  "command": "cmd",
  "args": ["/c", "bunx", "@carmeloricarte/gitlab-mcp-server"]
}

重要提示： 包名称必须始终为 最后一个论点 在args数组中。

Claude 代码命令行界面

Option A: All variables in config

claude mcp add-json GitLab '{
  "type": "stdio",
  "command": "bunx",
  "args": ["@carmeloricarte/gitlab-mcp-server"],
  "env": {
    "GITLAB_HOST": "https://your-gitlab.com",
    "GITLAB_TOKEN": "glpat-your-token",
    "NODE_TLS_REJECT_UNAUTHORIZED": "0"
  }
}'

Option B: Token from system env

集 GITLAB_TOKEN 作为系统变量（见上文），则：

claude mcp add-json GitLab '{
  "type": "stdio",
  "command": "bunx",
  "args": ["@carmeloricarte/gitlab-mcp-server"],
  "env": {
    "GITLAB_HOST": "https://your-gitlab.com",
    "NODE_TLS_REJECT_UNAUTHORIZED": "0"
  }
}'

验证：

claude mcp list
# Expected: GitLab: bunx ... - ✓ Connected

VS代码（带MCP扩展名）

编辑 ~/.vscode/mcp.json 或 .vscode/mcp.json 在您的项目中：

{
  "servers": {
    "GitLab": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@carmeloricarte/gitlab-mcp-server"],
      "env": {
        "GITLAB_HOST": "https://your-gitlab.com",
        "GITLAB_TOKEN": "glpat-your-token",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

光标

编辑 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "GitLab": {
      "command": "bunx",
      "args": ["@carmeloricarte/gitlab-mcp-server"],
      "env": {
        "GITLAB_HOST": "https://your-gitlab.com",
        "GITLAB_TOKEN": "glpat-your-token",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

泽德

编辑 ~/.config/zed/settings.json （macOS/Linux）或 %APPDATA%\Zed\settings.json （Windows）：

{
  "context_servers": {
    "GitLab": {
      "command": {
        "path": "bunx",
        "args": ["@carmeloricarte/gitlab-mcp-server"],
        "env": {
          "GITLAB_HOST": "https://your-gitlab.com",
          "GITLAB_TOKEN": "glpat-your-token",
          "NODE_TLS_REJECT_UNAUTHORIZED": "0"
        }
      }
    }
  }
}

OpenCode

编辑 ~/.config/opencode/config.json:

{
  "mcp": {
    "servers": {
      "GitLab": {
        "type": "stdio",
        "command": "bunx",
        "args": ["@carmeloricarte/gitlab-mcp-server"],
        "env": {
          "GITLAB_HOST": "https://your-gitlab.com",
          "GITLAB_TOKEN": "glpat-your-token",
          "NODE_TLS_REJECT_UNAUTHORIZED": "0"
        }
      }
    }
  }
}

Codex（OpenAI CLI）

编辑 ~/.codex/config.json:

{
  "mcpServers": {
    "GitLab": {
      "command": "bunx",
      "args": ["@carmeloricarte/gitlab-mcp-server"],
      "env": {
        "GITLAB_HOST": "https://your-gitlab.com",
        "GITLAB_TOKEN": "glpat-your-token",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

帆板运动

编辑 ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "GitLab": {
      "command": "bunx",
      "args": ["@carmeloricarte/gitlab-mcp-server"],
      "env": {
        "GITLAB_HOST": "https://your-gitlab.com",
        "GITLAB_TOKEN": "glpat-your-token",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

克劳德桌面版

编辑Claude Desktop配置文件：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "GitLab": {
      "command": "bunx",
      "args": ["@carmeloricarte/gitlab-mcp-server"],
      "env": {
        "GITLAB_HOST": "https://your-gitlab.com",
        "GITLAB_TOKEN": "glpat-your-token",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

可用工具

项目

list_projects -列出可访问的GitLab项目
get_project -获取特定项目的详细信息

分支

list_branches -列出项目中的分支
create_branch -创建新分支

问题

create_issue -创建新问题
list_issues -列出项目中的问题

合并请求

create_merge_request -创建合并请求
list_merge_requests -列出合并请求

文件

get_file -从存储库获取文件内容
create_or_update_file -创建或更新文件

搜索

search_code -在项目中搜索代码

发展

如果您想在本地贡献或运行服务器进行开发：

克隆并安装

git clone https://github.com/CarmeloRicarte/gitlab-mcp-server.git
cd gitlab-mcp-server
bun install

项目结构

src/
├── index.ts              # Entry point
├── server.ts             # MCP server setup
├── config.ts             # Environment configuration
├── client/
│   └── gitlab-client.ts  # GitLab API client
├── tools/
│   ├── index.ts          # Tool registration
│   ├── projects.ts
│   ├── branches.ts
│   ├── issues.ts
│   ├── merge-requests.ts
│   ├── files.ts
│   └── search.ts
└── types/
    └── gitlab.ts         # TypeScript types
scripts/
└── add-shebang.js        # Adds Node shebang to compiled output
tests/
├── setup.ts              # Test utilities & mocks
├── client/
│   └── gitlab-client.test.ts
└── tools/
    └── *.test.ts

运行服务器

bun run start
# or with hot reload
bun run dev

运行测试

# Run all tests
bun test

# Run with watch mode
bun test:watch

# Run with coverage
bun test:coverage

类型检查

bun run typecheck

构建

# Build for production (compiles to dist/index.js with Node.js compatibility)
bun run build

# Add shebang to compiled output (done automatically on publish)
bun run add-shebang

发布

通过以下方式自动发布到npm prepublishOnly:

npm version patch  # or minor/major
npm publish

这会自动：

将TypeScript编译为JavaScript(bun run build)
添加 #!/usr/bin/env node 谢邦(bun run add-shebang)

建筑

服务器对GitLab客户端使用依赖注入，使其在测试中易于模拟：

import { GitLabClient } from "./src/client/gitlab-client";
import { createServer } from "./src/server";

// For testing with a mock client
const mockClient = new GitLabClient({
  apiBase: "https://mock.gitlab.com/api/v4",
  token: "test-token",
});
const server = createServer(mockClient);

贡献

欢迎投稿！请随时打开问题并提取请求。

克隆该仓库
创建功能分支(git checkout -b feature/amazing-feature)
提交您的更改(git commit -m 'feat: add amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

请确保：

遵循现有代码样式
为新功能添加测试
根据需要更新文档

许可证

麻省理工学院