gitlab-code-reader-mcp
English
A lightweight MCP (Model Context Protocol) server that lets AI assistants read and explore GitLab repository code. Inspired by how Claude Code reads local codebases with its Read/Grep/Glob/LSP tools — but for remote GitLab repos.
9 focused tools. Single Go binary. Zero bloat.
Why?
Existing GitLab MCP servers expose 100+ tools covering every GitLab API. That's great for full GitLab automation, but it floods the AI's context with tool descriptions and makes code reading inefficient.
This project takes a different approach: do one thing well. Just code reading. The tool descriptions fit in ~500 tokens instead of thousands, and every tool is optimized for how AI assistants actually explore code.
Tools
Design Principles
Borrowed from Claude Code's architecture:
- Token is budget — Large files auto-truncate at 500 lines. Batch reads cap at 200 lines/file. Minified lines get cut at 500 chars.
- Symbols first — For files over 300 lines,
gl_read_symbolsreturns function/class signatures instead of dumping the whole file. - Caching — LRU cache for repository trees (5 min), file content (5 min), project info (10 min).
- Line numbers everywhere — All file output includes line numbers so the AI can reference "line 42" and use
start_line/end_lineto zoom in. - Guided errors — Instead of raw 404s, errors suggest what to try next.
- Built-in strategy — The MCP
instructionsfield teaches the AI when to use which tool.
Quick Start
Option 1: Go install (recommended)
go install github.com/nanami7777777/gitlab-code-reader-mcp/cmd/server@latest
GITLAB_TOKEN=glpat-xxx gitlab-code-reader-mcp
Option 2: Build from source
git clone https://github.com/nanami7777777/gitlab-code-reader-mcp.git
cd gitlab-code-reader-mcp
go build -o server ./cmd/server/
GITLAB_TOKEN=glpat-xxx ./server
Option 3: Docker
docker run --rm -e GITLAB_TOKEN=glpat-xxx -e GITLAB_URL=https://gitlab.example.com \
ghcr.io/nanami7777777/gitlab-code-reader-mcp
Option 4: Download binary
Grab a pre-built binary from Releases.
MCP Client Configuration
Add to your MCP config (Kiro: .kiro/settings/mcp.json, Claude Code: .claude/settings.json, Cursor: .cursor/mcp.json):
{
"mcpServers": {
"gitlab-code-reader": {
"command": "/path/to/gitlab-code-reader-mcp/server",
"args": [],
"env": {
"GITLAB_TOKEN": "glpat-xxx",
"GITLAB_URL": "https://gitlab.example.com"
}
}
}
}
Usage Examples
"Show me the directory structure of project mygroup/myproject" → gl_list_directory
"Find all Go files in the src directory" → gl_find_files
"Read the main entry point" → gl_read_file
"Search for where authentication is handled" → gl_search_code
"Show me what changed in MR !42" → gl_diff
"Who last modified the config file?" → gl_blame
Symbol Extraction
gl_read_symbols uses regex-based extraction. Supported: TypeScript/JavaScript, Python, Go, Java/Kotlin, Rust. Files under 300 lines return full content instead.
Benchmarks: vs @zereight/mcp-gitlab
40% less data transferred. 25% fewer tool calls. Measured, not estimated.
We benchmarked both MCP servers on the same task: "Understand how the Worker consumes MQ messages" in a real Go project (7 source files, ~1,500 lines total). The benchmark script calls the same GitLab API endpoints and measures the actual response sizes each MCP would return.
Task: Read 7 source files to understand MQ consumption architecture
────────────────────────────────────────────────────────────────────
New MCP Old MCP (@zereight)
Tool calls 6 8
Total response size 31.5 KB 52.3 KB
Response format plain text raw JSON + base64
Batch read support ✓ ✗
────────────────────────────────────────────────────────────────────
Savings 40% smaller baseline
2 fewer calls
Where the savings come from:
Run the benchmark yourself:
cd benchmark
GITLAB_TOKEN=glpat-xxx GITLAB_URL=https://gitlab.example.com go run main.go
Equivalent Tools
When to use which?
- This project → read and understand code
- @zereight/mcp-gitlab → write operations (create MRs, post comments, manage issues)
Architecture
cmd/server/main.go # Entry point
internal/gitlab/ # API client + cache
internal/tools/ # 9 tool implementations
internal/symbols/ # Regex-based symbol extraction
Contributing
See CONTRIBUTING.md. PRs welcome!
License
中文
一个轻量级 MCP（Model Context Protocol）服务器，让 AI 助手能够读取和探索 GitLab 仓库代码。灵感来自 Claude Code 读取本地代码的方式（Read/Grep/Glob/LSP 工具）——但面向远程 GitLab 仓库。
9 个专注工具。单个 Go 二进制。零冗余。
为什么做这个？
现有的 GitLab MCP 服务器暴露了 100+ 个工具，覆盖所有 GitLab API。这对全功能自动化很好，但会用工具描述淹没 AI 的上下文窗口，让代码读取变得低效。
本项目只做一件事：代码读取。工具描述只占 ~1,000 tokens，每个工具都针对 AI 探索代码的方式优化。
工具列表
设计原则
- Token 是预算 — 大文件自动截断 500 行，批量每文件 200 行，minified 行截断 500 字符
- 符号优先 — 超过 300 行的文件返回函数/类签名而非全文
- 缓存 — LRU 缓存：仓库树 5 分钟、文件 5 分钟、项目信息 10 分钟
- 行号无处不在 — 所有输出带行号，AI 可精确引用
- 指导性错误 — 错误信息建议下一步操作
- 内置策略 — MCP instructions 教 AI 按优先级选工具
快速开始
方式一：Go install（推荐）
go install github.com/nanami7777777/gitlab-code-reader-mcp/cmd/server@latest
GITLAB_TOKEN=glpat-xxx gitlab-code-reader-mcp
方式二：从源码构建
git clone https://github.com/nanami7777777/gitlab-code-reader-mcp.git
cd gitlab-code-reader-mcp
go build -o server ./cmd/server/
GITLAB_TOKEN=glpat-xxx ./server
方式三：Docker
docker run --rm -e GITLAB_TOKEN=glpat-xxx -e GITLAB_URL=https://gitlab.example.com \
ghcr.io/nanami7777777/gitlab-code-reader-mcp
方式四：下载二进制
从 Releases 下载预编译二进制。
MCP 客户端配置
添加到 MCP 配置文件（Kiro: .kiro/settings/mcp.json，Claude Code: .claude/settings.json，Cursor: .cursor/mcp.json）：
{
"mcpServers": {
"gitlab-code-reader": {
"command": "/path/to/gitlab-code-reader-mcp/server",
"args": [],
"env": {
"GITLAB_TOKEN": "glpat-xxx",
"GITLAB_URL": "https://gitlab.example.com"
}
}
}
}
使用示例
"看一下 mygroup/myproject 的目录结构" → gl_list_directory
"找一下 src 下所有 Go 文件" → gl_find_files
"读一下主入口文件" → gl_read_file
"搜一下哪里处理了认证" → gl_search_code
"看看 MR !42 改了什么" → gl_diff
"这个文件最后谁改的？" → gl_blame
性能对比：vs @zereight/mcp-gitlab
数据传输量减少 40%。工具调用减少 25%。实测数据，非估算。
我们用同一个任务对两个 MCP 做了基准测试："理解 Worker 如何消费 MQ 消息"，真实 Go 项目（7 个源文件，约 1,500 行）。Benchmark 脚本调用相同的 GitLab API，测量每个 MCP 实际返回的数据量。
任务：读取 7 个源文件，理解 MQ 消费架构
────────────────────────────────────────────────────────────────────
新 MCP 旧 MCP (@zereight)
工具调用次数 6 8
总响应大小 31.5 KB 52.3 KB
响应格式 纯文本 原始 JSON + base64
批量读取 ✓ ✗
────────────────────────────────────────────────────────────────────
节省 40% 更小 基准线
少 2 次调用
节省来自哪里：
自己运行 benchmark：
cd benchmark
GITLAB_TOKEN=glpat-xxx GITLAB_URL=https://gitlab.example.com go run main.go
等价工具
什么时候用哪个？
- 本项目 → 读取和理解代码
- @zereight/mcp-gitlab → 写操作（创建 MR、发评论、管理 issue）
贡献
参见 CONTRIBUTING.md。欢迎 PR！