Repomix MCP 服务器实战指南：让 AI 助手直接打包、搜索与读取代码库-港品优选

Repomix MCP 服务器实战指南：让 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) 为主体，结合src/mcp/目录下的源码实现，完整讲解--mcp与--sandbox的启动方式、VS Code / Cline / Cursor / Claude Desktop / Claude Code / Docker 六种客户端配置、全部 MCP 工具的参数与调用示例，以及沙盒模式的路径约束原理。读完后你可以把 Repomix 接入任意 MCP 客户端，让 AI 助手自主完成代码审查、文档生成、缺陷排查与大型代码库理解等任务。

[!NOTE] 这是一个实验性功能，项目会根据用户反馈和真实使用场景持续改进（仓库文档原文声明）。

Repomix 以 MCP 服务器模式运行

要启动 MCP 服务器，只需使用--mcp标志：

repomix --mcp

该命令会让 Repomix 进入 MCP 服务器模式，供任何支持 Model Context Protocol 的 AI 助手使用。从源码看，该参数在 cliRun.ts 的 MCP 选项组中定义：--mcp表示 "Run as Model Context Protocol server for AI tool integration"；当该选项被解析后，CLI 会动态导入 mcpAction.ts 并调用runMcpAction，最终进入 mcpServer.ts 的runMcpServer。

在 mcpServer.ts 中，createMcpServer基于官方@modelcontextprotocol/sdk创建服务器（服务器名称为repomix-mcp-server，版本号取自 Repomix 自身的版本），并通过StdioServerTransport与客户端通信——这正是 MCP 客户端配置中只需指定command与args即可工作的原因：Repomix 通过标准输入输出与 AI 助手交互。

MCP 工具注册逻辑

createMcpServer中的工具注册体现了沙盒模式的工具划分，这是理解后续所有工具的基础：

始终注册（只读、可在沙盒中约束）：pack_codebase、read_repomix_output、grep_repomix_output（mcpServer.ts）；
仅沙盒模式注册：file_system_read_file、file_system_read_directory（mcpServer.ts）——原因在注释中写得很清楚：非沙盒模式下它们可以读取进程可读的任何路径，秘密扫描只是内容启发式而非访问边界，只有在--sandbox下才存在诚实的边界；
非沙盒模式注册：pack_remote_repository、generate_skill、attach_packed_output以及远程打包的 prompt（mcpServer.ts）——远程抓取需要网络、技能生成会写文件、附加外部输出会读取任意路径，因此沙盒模式下全部禁用。

服务器还会根据模式注入不同的instructions：普通模式告知代理使用pack_codebase/pack_remote_repository打包、read_repomix_output/grep_repomix_output分析；沙盒模式则额外声明路径必须相对工作区根、禁止绝对路径 /~//../等（mcpServer.ts）。

沙盒模式（--sandbox）：把文件工具锁进单一工作区

默认情况下，MCP 服务器可以读取宿主用户可访问的任何路径。对可信的本地助手这很方便，但一旦服务器暴露给不可信客户端或代理，范围就过宽了。--sandbox标志把服务器的文件工具限制在单一工作区目录内：

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

从 cliRun.ts 的实现可以看到：--sandbox支持可选的目录参数（--sandbox [dir]），缺省时以当前工作目录为根；字符串值会被path.resolve解析并通过canonicalizeSandboxRoot规范化（使用realpath解析，失败时仍然关闭通道），随后以{ sandboxed, cwd: sandboxRoot }传入runMcpAction。同时，--sandbox不带--mcp时仅输出警告而不产生任何效果——它只影响 MCP 服务器。

沙盒模式的两条核心规则

开启沙盒模式后，行为遵循两条规则（仓库文档原文）：

所有路径都相对于工作区根。绝对路径、~、..以及 Windows 盘符 / UNC 路径会被拒绝；即便通过符号链接解析到根目录之外，路径也会被丢弃。结果与错误消息同样是相对路径，宿主路径不会暴露。这条规则同样适用于下文工具参考中的directory和path参数——沙盒模式下必须传工作区根相对路径，而非表中描述的绝对路径。
只注册只读、受根目录约束的工具：pack_codebase、read_repomix_output、grep_repomix_output、file_system_read_file、file_system_read_directory。远程打包、技能生成、附加外部输出因涉及网络访问、写文件或引用任意路径而被禁用。

在源码层面，路径约束的核心实现在 pathScope.ts：isEscapingPath判定输入是否为转义路径——path.isAbsolute覆盖 POSIX 的/x与 Windows 的C:\x、\x、UNC；正则^[a-zA-Z]:(?![/\\])额外捕获 Windows 盘符相对路径（如C:foo，path.isAbsolute会漏掉它）；~/~/主目录引用、任何..穿越段也被拒绝。resolveWithinRoot则完成三明治式校验：先做词法检查拒绝转义路径，再用path.resolve拼接候选路径并确认其仍在根内，最后通过realpath解析符号链接，捕获"根内的链接指向根外"的逃逸（pathScope.ts）。toVirtualPath负责把根内绝对路径转成根相对路径（根自身为.），用于展示层。

值得一提的细节是pack_codebase的沙盒加固：除了目录参数，includePatterns/ignorePatterns也要通过patternsEscapeRoot检查——该检查会先做 brace 展开（minimatch的braceExpand），防止"{/etc/**,x}"这种用花括号替代项夹带绝对路径的写法；同时沙盒下会强制skipLocalConfig、skipGlobalConfig、confineToBaseDir、gitSortByChanges: false，避免工作区的repomix.config.*通过output.instructionFilePath把工作区外文件读进输出、input.processors执行命令，或git -C <workspace> log读取不可信.git/config触发宿主命令执行（packCodebaseTool.ts）。

沙盒是应用层约束，不是操作系统沙箱

需要特别强调：这是对工具表面的应用层限制（纵深防御），并非操作系统级沙箱。当为不可信客户端托管服务器时，仍应将其运行在平台常规隔离手段之下（容器、专用用户）。错误处理同样遵循"不泄露宿主路径"原则：mcpToolRuntime.ts中的sandboxErrorReason只根据错误码映射白名单化的原因（ENOENT→ "not found"、EACCES/EPERM→ "permission denied"、EISDIR/ENOTDIR、ELOOP、EMFILE等，其余一律 "operation failed"），buildSandboxErrorResponse从不明文转发error.message，确保不可信代理在结构上无法获得宿主路径；完整的错误细节仍通过logger.error输出到操作员的 stderr。相关行为由 pathScope.test.ts 与tests/mcp/tools/下的 sandbox 契约测试端到端断言。

在主流客户端中配置 Repomix MCP 服务器

要配合 Claude 等 AI 助手使用，需要在客户端侧配置 MCP 服务器。

VS Code

VS Code 中可通过两种方式安装：

安装徽章：点击仓库文档中的 VS Code / VS Code Insiders 安装徽章即可一键注册（其底层对应vscode:mcp/installURI，携带的配置为npx -y 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中添加与 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" ] } } }

注意 Docker 方式使用-i保持标准输入打开、--rm在退出后自动清理容器，这正是 stdio 传输所需的运行形态。

可用的 MCP 工具详解

以 MCP 服务器运行时，Repomix 提供以下工具。所有工具的输入输出 Schema 都在对应源码文件中用 zod 定义，并通过registerTool注册（见src/mcp/tools/目录）。

pack_codebase：打包本地代码目录

把本地代码目录打包为供 AI 分析的合并文件。它分析代码库结构、提取相关代码内容，生成包含指标（metrics）、文件树（file tree）和格式化代码内容的综合报告。

参数：

参数	必填	默认值	说明
`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 }`条目数组。首个匹配的 pattern 生效；`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作为未匹配文件的 catch-all），src/core/下的文件保留完整内容，docs/下的文件仅出现在目录结构中，其余文件全部压缩。

从实现看，pack_codebase内部复用了完整的 CLI 打包管线：在临时目录（getRepomixTmpDir()下的mcp-outputs）中生成输出文件，再以compress、include、ignore、outputPatterns、style、securityCheck: true等选项调用runCli，并把quiet: true期间的全局日志级别保存/恢复，避免静默模式永久屏蔽操作员的 stderr 日志（packCodebaseTool.ts）。打包成功后返回outputId、outputFilePath、totalFiles、totalTokens等结构化结果；在沙盒模式下outputFilePath与宿主目录会被隐藏，仅暴露outputId供read_repomix_output使用（mcpToolRuntime.ts）。

pack_remote_repository：打包远程 GitHub 仓库

抓取、克隆 GitHub 仓库并打包为供 AI 分析的合并文件。它会自动克隆远程仓库、分析结构并生成综合报告。

参数：

参数	必填	默认值	说明
`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%。一般不需要，因为`grep_repomix_output`支持增量检索
`includePatterns`	否	—	用 fast-glob 模式指定要包含的文件，逗号分隔（如`"*/.{js,ts}"`、`"src/,docs/"`）
`ignorePatterns`	否	—	用 fast-glob 模式指定额外排除的文件，逗号分隔（如`"test/*,.spec.js"`）。补充`.gitignore`与内置排除规则
`outputPatterns`	否	—	逐文件包含级别，形式与`pack_codebase`相同，会覆盖目标仓库配置
`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 }

实现上，该工具同样复用 CLI 的--remote打包管线，并且回显的仓库地址会经过redactUrl脱敏处理——带凭据的远程地址不会残留在 MCP 对话记录、客户端日志和模型上下文中（packRemoteRepositoryTool.ts）。该工具仅在非沙盒模式下注册。

read_repomix_output：读取 Repomix 输出文件

读取 Repomix 生成的输出文件内容，支持通过行号区间对大文件进行部分读取。该工具专为直接文件系统访问受限的环境设计。

参数：

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

特性：

专为基于 Web 的环境或沙盒应用设计；
通过 ID 检索之前生成的输出内容；
无需文件系统访问即可读取打包后的代码库；
支持大文件的部分读取。

示例：

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

源码中，输出文件注册在mcpToolRuntime.ts的outputFileRegistry内存映射中，outputId由crypto.randomBytes(8).toString('hex')生成，read_repomix_output据此反查文件路径；行号参数做了完整校验（起始行必须 ≥1、起始行不得大于结束行、起始行不得超出文件总行数），并返回content、totalLines、linesRead等结构化结果（readRepomixOutputTool.ts）。对于通过attach_packed_output从不可信路径附加的输出，每次提供内容前都会先运行 Secretlint 秘密格式扫描（requiresSecretScan为真时）。

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 }

实现上，createRegexPattern根据ignoreCase构造gi或g标志的正则并捕获非法正则错误；performGrepSearch只在开始时切分一次内容，同时复用于搜索与格式化，避免在 3–5 MB 的大输出文件上做重复的 O(n) 切分；formatSearchResults会生成类似行号:（匹配行）与行号-（上下文行）的 grep 风格输出，并用--分隔不连续的上下文块（grepRepomixOutputTool.ts）。

file_system_read_file 与 file_system_read_directory

这两个文件系统工具仅在沙盒模式（--sandbox）下可用，由工作区根限定可达范围；不带--sandbox时不会注册。

file_system_read_file
- 读取相对于工作区根路径（如src/index.ts）的文件内容；
- 会拒绝匹配已知秘密格式（Secretlint）的内容，作为额外的启发式安全措施——访问边界是工作区根，而非扫描本身；
- 对无效路径返回清晰错误消息，且不暴露宿主路径。
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' });

从源码看，这两个工具通过resolveToolPath统一处理两种模式：非沙盒下沿用"绝对路径"契约（并在入口处强制path.isAbsolute校验），沙盒下先resolveWithinRoot约束路径、再用toVirtualPath虚拟化展示路径，避免宿主绝对路径出现在输出中（mcpToolRuntime.ts）。目录工具会返回contents、totalItems、fileCount、directoryCount等结构化信息（fileSystemReadDirectoryTool.ts）。

这些工具在 AI 助手需要以下场景时特别有用：分析工作区中的特定文件、导航目录结构、确认文件是否存在及可访问性。

使用 Repomix 作为 MCP 服务器的优势

直接集成：AI 助手无需手动准备文件即可直接分析代码库。
高效工作流：省去手动生成和上传文件的环节，简化代码分析流程。
一致输出：AI 助手以一致、优化的格式接收代码库内容。
高级功能：可充分利用 Repomix 的代码压缩、token 计数、安全检测等全部能力。

配置完成后，AI 助手即可直接调用 Repomix 的能力分析代码库，让代码分析工作流更加高效。

企业官网建设流程全解析