Repomix MCP Server 实战指南：让 AI 助手直接打包、检索与读取你的代码库-编程实验室

Repomix MCP Server 实战指南：让 AI 助手直接打包、检索与读取你的代码库

【免费下载链接】repomix📦 Repomix is a powerful tool that packs your entire repository into a single, AI-friendly file. Perfect for when you need to feed your codebase to Large Language Models (LLMs) or other AI tools like Claude, ChatGPT, DeepSeek, Perplexity, Gemini, Gemma, Llama, Grok, and more.项目地址: https://gitcode.com/GitHub_Trending/rep/repomix

导读

Repomix 支持 Model Context Protocol (MCP) 为核心骨架，结合仓库源码，系统讲解如何将 Repomix 作为 MCP 服务器运行、配置到 VS Code / Cline / Cursor / Claude Desktop / Claude Code 等 AI 客户端、理解--sandbox沙箱安全边界，以及逐个掌握 6 个可用 MCP 工具的完整参数与调用示例。读完本文，你将能把代码库分析工作流无缝接入任意 MCP 兼容的 AI 助手，并在安全与效率之间取得平衡。

[!NOTE] 这是一个实验性特性，团队将根据用户反馈和真实世界使用情况持续改进它。

快速开始：以 MCP 服务器模式运行 Repomix

在终端中执行：

repomix --mcp

该命令将 Repomix 以 MCP 服务器模式启动，通过标准输入输出（stdio）与支持 Model Context Protocol 的 AI 助手通信。从源码看，mcpAction.ts 将工作目录（cwd）作为服务器根目录传入runMcpServer；而 mcpServer.ts 使用StdioServerTransport建立连接，并在收到SIGINT/SIGTERM信号时优雅关闭服务器。

启动后，Repomix 默认注册 6 个打包与分析类工具（见 mcpServer.ts），并在服务器指令中向 AI 助手描述其能力：先用pack_codebase或pack_remote_repository将代码整合为单个 XML 文件，再用read_repomix_output和grep_repomix_output进行分析。

安全边界：Sandbox 沙箱模式

默认情况下，MCP 服务器可以读取运行用户可访问的任何路径。这对可信的本地助手很方便，但当服务器暴露给不受信任的客户端或 Agent 时，范围就过于宽泛了。--sandbox标志将服务器的文件工具限制在单个工作区目录内：

# 限制在当前工作目录 repomix --mcp --sandbox # 限制在指定目录 repomix --mcp --sandbox path/to/project

开启沙箱模式后：

每个路径都相对于工作区根目录。绝对路径、~、..以及 Windows 驱动器/UNC 路径都会被拒绝，解析到根目录之外的路径（包括通过符号链接解析的）会被丢弃。结果和错误消息也是相对的，因此不会暴露主机路径。这也适用于下文工具参考中的directory和path参数：在沙箱模式下，请将它们作为相对于工作区根目录的路径传递，而不是表格中通常描述的绝对路径。
仅注册只读、限定根目录的工具：pack_codebase、read_repomix_output、grep_repomix_output、file_system_read_file和file_system_read_directory。远程打包、技能生成和附加外部输出会被禁用，因为它们需要访问网络、写入文件或引用任意路径。两个file_system_*工具本身也仅在沙箱模式下可用，其可访问范围由工作区根目录界定。

需要特别说明的是，这不是操作系统级别的沙箱，而是工具表面的应用级限制（纵深防御）。为不受信任的客户端托管服务器时，仍应在平台常规隔离手段（容器、专用用户）下运行。

从实现上看，沙箱边界的核心在 pathScope.ts：isEscapingPath拒绝绝对路径、Windows 相对驱动器路径（如C:foo）、~家目录引用和任何..穿越段；resolveWithinRoot进一步通过realpath解析符号链接，确保指向根目录之外的链接同样被拦截。此外，cliRun.ts 在--sandbox生效时会跳过工作区的repomix.config.*与全局配置（防止配置文件读取工作区外文件或执行命令）、将文件搜索限定在根目录，并禁用基于 git 的排序（git log可能读取不受信任的.git/config成为主机命令执行向量）。若仅指定--sandbox而未配合--mcp，它会警告“无效果”，因为它只影响 MCP 服务器。

配置 MCP 服务器：各主流 AI 客户端接入方式

VS Code

安装 Repomix MCP 服务器有两种方式：

方式一：使用安装徽章（点击即可注入配置）

方式二：使用命令行

code --add-mcp '{"name":"repomix","command":"npx","args":["-y","repomix","--mcp"]}'

VS Code Insiders 对应：

code-insiders --add-mcp '{"name":"repomix","command":"npx","args":["-y","repomix","--mcp"]}'

Cline（VS Code 插件）

编辑cline_mcp_settings.json文件：

{ "mcpServers": { "repomix": { "command": "npx", "args": [ "-y", "repomix", "--mcp" ] } } }

Cursor

在 Cursor 中，通过Cursor Settings>MCP>+ Add new global MCP server添加新的 MCP 服务器，配置与 Cline 类似。

Claude Desktop

编辑claude_desktop_config.json文件，配置与 Cline 类似。

Claude Code

在 Claude Code 中配置：

claude mcp add repomix -- npx -y repomix --mcp

另外，若希望获得更便捷的体验，可以使用官方 Repomix 插件——插件提供自然语言命令和更简单的安装方式，详见 Claude Code 插件指南。

使用 Docker 代替 npx

无需 npx，也可以用 Docker 运行 Repomix MCP 服务器：

{ "mcpServers": { "repomix-docker": { "command": "docker", "args": [ "run", "-i", "--rm", "ghcr.io/yamadashy/repomix", "--mcp" ] } } }

MCP 工具详解（一）：代码打包类

pack_codebase：打包本地代码库

该工具将本地代码目录打包为适合 AI 分析的合并 XML 文件。它会分析代码库结构、提取相关代码内容，并生成包含指标、文件树和格式化代码内容的综合报告。

参数说明：

参数	必填	默认值	说明
`directory`	是	—	要打包的目录路径。沙箱模式下为相对工作区根目录的路径（如`"."`或`"src"`）；非沙箱模式为绝对路径
`compress`	否	`false`	启用 Tree-sitter 压缩，提取核心代码签名和结构并移除实现细节。可将 Token 用量减少约 70% 同时保留语义。由于`grep_repomix_output`支持增量内容获取，通常不需要开启
`includePatterns`	否	—	使用 fast-glob 模式指定要包含的文件，逗号分隔（如`"*/.{js,ts}"`、`"src/,docs/"`）
`ignorePatterns`	否	—	使用 fast-glob 模式指定额外排除的文件，逗号分隔（如`"test/*,.spec.js"`），补充`.gitignore`和内置排除规则
`outputPatterns`	否	—	按文件设置包含级别，镜像配置文件中的`output.patterns`选项。数组元素形如`{ "pattern": string, "compress"?: boolean, "directoryStructureOnly"?: boolean }`。第一个匹配的模式生效；`directoryStructureOnly`优先于`compress`；两个标志都未设置时强制完整内容（可用于豁免全局`compress`的文件）。会覆盖目标仓库`repomix.config.json`中的所有`output.patterns`设置
`topFilesLength`	否	`10`	指标摘要中按大小展示的最大文件数量
`style`	否	`xml`	输出格式风格：`xml`、`markdown`、`json`或`plain`

调用示例：

{ "directory": "/path/to/your/project", "compress": true, "includePatterns": "src/**/*.ts,**/*.md", "ignorePatterns": "**/*.log,tmp/", "outputPatterns": [ { "pattern": "src/core/**" }, { "pattern": "docs/**/*", "directoryStructureOnly": true } ], "topFilesLength": 10 }

在上面的例子中（compress: true作为未匹配文件的兜底规则），src/core/下的文件保持完整内容，docs/下的文件仅在目录结构中列出，其余所有文件被压缩。

实现细节：该工具的输入模式定义在 packCodebaseTool.ts。打包实际复用了 CLI 主流程runCli，因此 Tree-sitter 压缩、安全扫描（securityCheck: true）、token 计数等 Repomix 全部能力都自动生效。打包产物写入临时工作区（createToolWorkspace），并生成唯一的outputId注册到内存注册表，供read_repomix_output/grep_repomix_output后续访问。沙箱模式下，工具还会预先校验 include/ignore 模式（对花括号展开后的每一项做isEscapingPath检查，防止"{/etc/**,x}"这类模式夹带绝对路径）与目录存在性，并跳过本地/全局配置文件、限制搜索范围、禁用 git 排序。

pack_remote_repository：打包远程 GitHub 仓库

该工具获取、克隆并将 GitHub 仓库打包为适合 AI 分析的合并 XML 文件。它会自动克隆远程仓库、分析其结构并生成综合报告。

参数说明：

参数	必填	默认值	说明
`remote`	是	—	GitHub 仓库 URL 或`user/repo`格式（如`"yamadashy/repomix"`、`"https://github.com/user/repo"`或`"https://github.com/user/repo/tree/branch"`）
`compress`	否	`false`	同上：启用 Tree-sitter 压缩，Token 用量减少约 70%
`includePatterns`	否	—	同上：fast-glob 包含模式，逗号分隔
`ignorePatterns`	否	—	同上：fast-glob 排除模式，逗号分隔
`outputPatterns`	否	—	同上：按文件设置包含级别
`topFilesLength`	否	`10`	指标摘要中的最大文件数量
`style`	否	`xml`	输出格式风格：`xml`、`markdown`、`json`或`plain`

调用示例：

{ "remote": "yamadashy/repomix", "compress": true, "includePatterns": "src/**/*.ts,**/*.md", "ignorePatterns": "**/*.log,tmp/", "outputPatterns": [ { "pattern": "src/core/**" }, { "pattern": "docs/**/*", "directoryStructureOnly": true } ], "topFilesLength": 10 }

实现细节：该工具仅在非沙箱模式下注册（mcpServer.ts），因为远程获取需要网络访问。实现上同样复用runCli的远程模式，且回显给 Agent 的仓库地址会经过redactUrl脱敏处理（packRemoteRepositoryTool.ts），避免带凭据的远程地址残留在 MCP 对话记录中。

MCP 工具详解（二）：输出检索类

打包完成后，AI 助手通过outputId对产物进行增量分析，无需直接访问文件系统——这正是大型仓库 Token 优化的关键。

read_repomix_output：读取打包输出

该工具读取 Repomix 生成的输出文件内容，支持通过行范围对大型文件进行部分读取。专为文件系统访问受限的环境（如 Web 环境、沙箱应用）设计。

参数说明：

参数	必填	默认值	说明
`outputId`	是	—	要读取的 Repomix 输出文件 ID
`startLine`	否	文件开头	起始行号（1 基，含该行）
`endLine`	否	文件末尾	结束行号（1 基，含该行）

特性：

专为 Web 环境或沙箱应用设计
通过 ID 获取此前生成的输出内容
无需文件系统访问即可读取打包后的代码库
支持大型文件的部分读取

调用示例：

{ "outputId": "8f7d3b1e2a9c6054", "startLine": 100, "endLine": 200 }

实现细节：outputId由crypto.randomBytes(8).toString('hex')生成，并连同输出文件路径注册到内存注册表（mcpToolRuntime.ts）。读取时若指定行范围，会先校验行号为正数且startLine <= endLine，再按区间切片返回content、totalLines、linesRead等结构化结果（readRepomixOutputTool.ts）。

grep_repomix_output：在输出中检索模式

该工具使用 grep 式功能（JavaScript RegExp 语法）在 Repomix 输出文件中搜索模式，返回匹配行及可选的上下文行。

参数说明：

参数	必填	默认值	说明
`outputId`	是	—	要搜索的 Repomix 输出文件 ID
`pattern`	是	—	搜索模式（JavaScript RegExp 语法）
`contextLines`	否	`0`	每个匹配前后显示的上下文行数；指定了`beforeLines`/`afterLines`时被覆盖
`beforeLines`	否	—	每个匹配前显示的行数（类似`grep -B`），优先于`contextLines`
`afterLines`	否	—	每个匹配后显示的行数（类似`grep -A`），优先于`contextLines`
`ignoreCase`	否	`false`	是否执行大小写不敏感匹配

特性：

使用 JavaScript RegExp 语法进行强大的模式匹配
支持上下文行以便更好理解匹配结果
允许分别控制前后上下文行数
支持大小写敏感与不敏感搜索

调用示例：

{ "outputId": "8f7d3b1e2a9c6054", "pattern": "function\\s+\\w+\\(", "contextLines": 3, "ignoreCase": false }

实现细节：搜索实现位于 grepRepomixOutputTool.ts。内容先按行切分一次（避免对 3~5MB 大文件重复 O(n) 拆分），逐行用new RegExp(pattern, flags)匹配，再按beforeLines/afterLines输出带行号前缀的格式化结果（匹配行用行号:前缀，上下文行用行号-前缀，间断处插入--分隔符）。无效正则会被捕获并返回明确错误。

MCP 工具详解（三）：沙箱文件系统工具

file_system_read_file与file_system_read_directory两个文件系统工具仅在沙箱模式（--sandbox）下可用，工作区根目录界定其可访问范围；不使用--sandbox时它们不会被注册（mcpServer.ts）。

file_system_read_file
- 读取工作区根目录相对路径的文件内容（如src/index.ts）
- 作为额外的启发式防护，拒绝匹配已知敏感信息格式（Secretlint，如 API Key、密码）的内容——访问边界是工作区根目录，而不是扫描
- 对无效路径返回清晰错误消息，且不暴露主机路径
file_system_read_directory
- 列出工作区根目录相对路径的目录内容（如.或src）
- 以明确指示符（[FILE]或[DIR]）展示文件和目录
- 适用于探索项目结构、理解代码库组织方式

调用示例：

// 读取文件 const fileContent = await tools.file_system_read_file({ path: 'src/index.ts' }); // 列出目录内容 const dirContent = await tools.file_system_read_directory({ path: 'src' });

这些工具在 AI 助手需要以下场景时尤其有用：

分析工作区中的特定文件
在目录结构中导航
验证文件的存在性与可访问性

实现细节：文件读取会先fs.stat区分文件/目录，读取后通过createSecretLintConfig+runSecretLint做敏感信息扫描，命中则拒绝返回（fileSystemReadFileTool.ts）。目录列出使用fs.readdir的withFileTypes选项生成[FILE]/[DIR]前缀，并附带totalItems、fileCount、directoryCount统计（fileSystemReadDirectoryTool.ts）。沙箱模式下，路径统一经过resolveToolPath→resolveWithinRoot的根目录约束与虚拟化（主机路径不会出现在任何返回内容与错误消息中）；错误消息由sandboxErrorReason白名单（not found、permission denied、path is a directory等固定原因）与 Agent 自身的输入拼接而成，结构上杜绝了主机路径泄露（mcpToolRuntime.ts）。

使用 Repomix MCP 服务器的核心优势

直接集成：AI 助手无需手动准备文件即可直接分析代码库。
高效工作流：消除手动生成和上传文件的步骤，简化代码分析流程。
一致输出：确保 AI 助手以一致、优化的格式接收代码库。
高级特性：充分利用 Repomix 的代码压缩、Token 计数、安全扫描等全部能力。

配置完成后，你的 AI 助手可以直接使用 Repomix 的能力分析代码库，让代码分析工作流更高效。上述工具集与安全机制均有对应的测试保障，例如 mcpServer.test.ts 验证了非沙箱模式注册 6 个打包/分析工具、沙箱模式仅注册 5 个只读工具的行为，pathScope.test.ts 则覆盖了根目录逃逸拦截等路径边界用例。