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/repomixRepomix 支持将自身以 Model Context ProtocolMCP服务器的方式运行使 Claude、Cursor、Cline 等 AI 助手能够直接与你的代码库交互无需手工准备文件即可完成本地/远程仓库的打包、检索与读取。本文基于 Repomix 官方文档与仓库源码完整讲解--mcp启动方式、--sandbox沙箱模式、各主流客户端的接入配置以及六种 MCP 工具的每个参数与底层实现帮助你快速把 Repomix 接入自己的 AI 编程工作流。[!NOTE] MCP 服务器是一个实验性功能官方会根据用户反馈与真实使用场景持续改进。以 MCP 服务器模式运行 Repomix启动命令与运行机制MCP 服务器模式通过--mcp标志启动repomix --mcp该命令将 Repomix 切换到 MCP 服务器模式供支持 Model Context Protocol 的 AI 助手使用。从源码看--mcp与--sandbox选项在 cliRun.ts 中解析随后动态加载 mcpAction.ts最终调用 mcpServer.ts 中的runMcpServer启动服务器服务器基于官方modelcontextprotocol/sdk构建通过StdioServerTransport以标准输入/输出stdio与客户端通信见 mcpServer.ts服务器名称为repomix-mcp-server版本号取自包信息服务器注册了SIGINT/SIGTERM信号处理退出时优雅关闭连接。服务器启动时会向客户端下发 instructions 说明intro/outro声明其能力使用pack_codebase或pack_remote_repository将代码整合为单个 XML 文件再用read_repomix_output与grep_repomix_output分析内容适用于代码评审、文档生成、Bug 排查、GitHub 仓库分析与大型代码库理解等场景。首次运行与输出 ID 机制执行打包类工具后Repomix 会返回一个唯一的outputId由crypto.randomBytes(8)生成的 16 位十六进制字符串见 mcpToolRuntime.ts并把生成的文件路径登记到进程内的outputFileRegistry映射表中。后续read_repomix_output/grep_repomix_output只需凭outputId即可读取内容无需直接访问文件系统——这正是面向 Web 或沙箱环境设计的核心机制。Sandbox 沙箱模式把文件工具锁进单一工作区默认情况下MCP 服务器可以读取宿主用户可访问的任何路径。这对可信的本地助手很方便但当服务器暴露给不受信任的客户端或 Agent 时权限范围过宽。--sandbox标志可将服务器的文件工具限制在单个 workspace 目录内# 限制到当前工作目录 repomix --mcp --sandbox # 限制到指定目录 repomix --mcp --sandbox path/to/project--sandbox的取值既可以是布尔值也可以是目录字符串见 cliRun.ts传字符串时即指定 workspace 根目录会先经过 realpath 规范化并校验存在性不传则默认使用当前工作目录。注意--sandbox只影响 MCP 服务器没有--mcp时它不产生任何效果CLI 会给出警告提示。沙箱模式下的两条核心规则所有路径均相对 workspace 根目录绝对路径、~、..以及 Windows 盘符/UNC 路径都会被拒绝通过 symlink 解析后逃出根目录的路径同样被丢弃。返回结果与错误信息也全部是相对路径不会暴露宿主路径。这一点适用于下文工具参考中的directory与path参数沙箱模式下必须传入相对 workspace 根目录的路径而不是其他场景所描述的绝对路径。只注册只读且被根目录约束的工具pack_codebase、read_repomix_output、grep_repomix_output、file_system_read_file、file_system_read_directory。远程打包、skill 生成与外部输出附加pack_remote_repository、generate_skill、attach_packed_output被禁用因为这些操作会访问网络、写文件或引用任意路径。两个file_system_*工具本身也只在沙箱模式下注册见 mcpServer.ts。路径守卫的底层实现沙箱的路径约束由 pathScope.ts 实现关键函数为isEscapingPath与resolveWithinRootisEscapingPath会拒绝path.isAbsolute判定为绝对路径的输入POSIX 的/x、Windows 的C:\x、\x、UNC盘符相对路径C:foopath.isAbsolute会漏掉这种形式而它在 Windows 上会按该盘符自身的 cwd 解析从而逃逸根目录~/~/主目录引用任何..穿越段无论哪种分隔符。仅以~开头的普通文件名如~$lock.docx被放行resolveWithinRoot在词法解析之外还会对目标与根目录做realpath解析通过 symlink 指向根目录外部的路径也会被拦截若目标尚不存在则回退到已受词法约束的路径toVirtualPath负责把根目录内的绝对路径转回相对路径根目录本身显示为.用于沙箱下的展示与错误信息确保不泄露宿主路径。此外pack_codebase在沙箱模式下还针对 include/ignore 模式做了花括号展开级的逃逸检查patternsEscapeRoot会先用与打包器一致的splitPatternsbrace-aware分词再对每个 token 做braceExpand防止{/etc/**,x}这类模式把绝对路径替代项夹带进 glob见 packCodebaseTool.ts。这类无法静态预展开的语法还会被下游searchFiles中语法无关的confineToBaseDir兜底丢弃——沙箱是纵深防御的应用层约束。沙箱模式下额外的加固在pack_codebase中沙箱模式还会一次性关闭多项配置见 packCodebaseTool.tsskipLocalConfig/skipGlobalConfig跳过目标仓库与操作者的全部 repomix 配置文件防止配置驱动的output.instructionFilePath把工作区外的文件读进 Agent 可见输出或input.processors执行命令confineToBaseDir把文件搜索约束在根目录内作为模式检查的语法无关兜底gitSortByChanges: false禁用基于 git 的排序因为git -C workspace log会读取不受信任工作区的.git/config例如通过log.showSignature触发gpg.program构成宿主命令执行面。错误处理层面buildSandboxErrorResponse采用白名单式的错误原因映射mcpToolRuntime.ts只依据错误码ENOENT→ not found、EACCES/EPERM→ permission denied 等生成固定原因绝不转发error.message从结构上保证宿主路径无法泄露PathScopeError是唯一例外其消息由 Agent 自己的输入加路径规则构成安全且有用。该保证由 sandbox.contract.test.ts 端到端断言。需要强调这是应用层的工具面约束纵深防御不是操作系统级沙箱。为不受信任的客户端托管服务器时仍应在平台常规隔离手段容器、专用用户下运行。配置 MCP 服务器要将 Repomix 用作 Claude 等 AI 助手的 MCP 服务器需要配置 MCP 定义。以下是各主流客户端的接入方式。VS CodeVS Code 可用两种方式安装使用安装徽章点击官方的 Install Server 徽章一键安装VS Code / VS Code Insiders 各有对应入口使用命令行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]}ClineVS Code 扩展编辑cline_mcp_settings.json文件{ mcpServers: { repomix: { command: npx, args: [ -y, repomix, --mcp ] } } }Cursor在 Cursor 中通过Cursor SettingsMCP 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 ] } } }使用-i保持 stdin 打开与--rm退出即删除容器是 MCP stdio 通信的关键——服务器通过标准输入输出与客户端对话容器必须保持交互式运行。MCP 可用工具详解以 MCP 服务器模式运行时Repomix 提供以下工具参数均经 zod schema 校验见各工具源码。以下是完整参数参考。pack_codebase打包本地代码目录该工具将本地代码目录打包为合并文件供 AI 分析。它会分析代码库结构、提取相关代码内容并生成包含指标metrics、文件树file tree与格式化代码内容的综合报告。支持多种输出格式XML带file标签的结构化格式、Markdown带##标题与代码块、JSON以键值对表示文件、Plain带分隔符的纯文本。参数参数必填默认值说明directory是—要打包的目录路径。非沙箱模式下为绝对路径任何该进程可读的目录均可打包沙箱模式下须为相对 workspace 根目录的路径如.或srccompress否false启用 Tree-sitter 压缩提取关键代码签名与结构、去掉实现细节。可减少约 70% token 用量并保留语义。通常无需开启因为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.patternstopFilesLength否10在指标摘要中按大小显示的最大文件数量源码中约束为 ≥1 的整数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/下的文件仅在目录结构中列出其余全部被压缩。pack_codebase底层通过runCli([.], targetDirectory, cliOptions)复用 Repomix 的打包流水线见 packCodebaseTool.ts打包输出写入 Repomix 临时目录下的mcp-outputs子目录同时强制开启安全扫描securityCheck: true。返回结果包含description、resultJSON 指标、directoryStructure、outputId、outputFilePath、totalFiles、totalTokens等结构化字段并在描述中附上打包文件的 XML 结构说明引导 Agent 用read_repomix_output按outputId读取。沙箱模式下outputFilePath会被置空避免暴露宿主路径。pack_remote_repository打包远程 GitHub 仓库该工具获取、克隆并打包 GitHub 仓库为合并文件供 AI 分析。它自动克隆远程仓库、分析其结构并生成综合报告。仅非沙箱模式注册需访问网络。返回的仓库描述信息会经redactUrl脱敏避免带凭据的远程地址残留在 MCP 会话记录与模型上下文中见 packRemoteRepositoryTool.ts。参数参数必填默认值说明remote是—GitHub 仓库 URL 或user/repo格式如yamadashy/repomix、https://github.com/user/repo或https://github.com/user/repo/tree/branchcompress否false同pack_codebase启用 Tree-sitter 压缩减少约 70% token 用量includePatterns否—同pack_codebasefast-glob 模式逗号分隔ignorePatterns否—同pack_codebase补充.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 }read_repomix_output按行区间读取打包输出该工具读取 Repomix 生成的输出文件内容支持通过行号区间对大文件进行部分读取专为直接文件系统访问受限的环境如 Web 环境、沙箱应用设计。参数参数必填默认值说明outputId是—要读取的 Repomix 输出文件 IDstartLine否文件开头起始行号从 1 开始含该行endLine否文件末尾结束行号从 1 开始含该行功能特性专为基于 Web 或沙箱化的环境设计通过 ID 检索此前生成的输出内容无需文件系统访问即可获取打包后的代码库支持大文件的部分读取示例{ outputId: 8f7d3b1e2a9c6054, startLine: 100, endLine: 200 }源码层面见 readRepomixOutputTool.ts该工具先从outputFileRegistry解析outputId对应的文件路径读取全部内容后按行切片参数校验严格——startLine/endLine必须 ≥1、startLine不得大于endLine、起始行不得超出文件总行数返回content、totalLines、linesRead、实际使用的startLine/endLine。对于经由attach_packed_output从不受信任路径挂载的输出每次提供内容前都会运行 Secretlint 秘密格式扫描requiresSecretScan机制作为额外启发式防护。grep_repomix_output正则检索打包输出该工具使用类 grep 功能在 Repomix 输出文件中检索模式采用 JavaScript RegExp 语法返回匹配行并可附带匹配前后的上下文行。参数参数必填默认值说明outputId是—要检索的 Repomix 输出文件 IDpattern是—检索模式JavaScript RegExp 正则语法contextLines否0每个匹配前后显示的上下文行数。指定了beforeLines/afterLines时被覆盖beforeLines否—每个匹配前显示的行数类似grep -B。优先于contextLinesafterLines否—每个匹配后显示的行数类似grep -A。优先于contextLinesignoreCase否false是否执行大小写不敏感匹配功能特性使用 JavaScript RegExp 语法实现强大模式匹配支持上下文行以便更好理解匹配结果可分别控制匹配前/后的上下文行数支持大小写敏感与不敏感检索示例{ outputId: 8f7d3b1e2a9c6054, pattern: function\\s\\w\\(, contextLines: 3, ignoreCase: false }源码实现见 grepRepomixOutputTool.ts先按行切分内容用new RegExp(pattern, ignoreCase ? gi : g)逐行匹配非法正则会抛出明确错误再基于beforeLines/afterLines生成带行号:命中行与行号-上下文行前缀的格式化输出匹配间隙以--分隔返回matches含lineNumber、line、matchedText、formattedOutput、totalMatches、pattern。与read_repomix_output一样对不受信任挂载的输出会先执行秘密扫描。这使 Agent 可以先打包一次再按需增量检索特定符号或模式这正是文档建议通常不必开启compress的原因。file_system_read_file 与 file_system_read_directory沙箱内的文件系统工具这两个文件系统工具仅在沙箱模式--sandbox下可用workspace 根目录界定了它们可访问的范围没有--sandbox时不会被注册见 mcpServer.ts。file_system_read_file读取相对 workspace 根目录路径下的文件内容如src/index.ts会拒绝与已知秘密格式Secretlint匹配的内容作为额外的启发式防护——访问边界是 workspace 根目录而不是扫描本身对无效路径返回清晰错误信息且不暴露宿主路径。file_system_read_directory列出相对 workspace 根目录的目录内容如.或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 助手需要以下能力时尤其有用分析工作区中的特定文件浏览目录结构确认文件的存在性与可访问性。路径参数由resolveToolPath统一处理mcpToolRuntime.ts沙箱模式下经resolveWithinRoot限定并虚拟化为相对路径展示非沙箱模式则沿用绝对路径契约。另有pack_codebase、pack_remote_repository之外的generate_skill由代码库生成 Claude Agent Skills与attach_packed_output挂载既有打包输出两个非沙箱工具共同构成完整的 MCP 工具面相关说明可参考 packRemoteRepositoryPrompts.ts。使用 Repomix MCP 服务器的收益将 Repomix 用作 MCP 服务器可带来多项优势直接集成AI 助手无需手工准备文件即可直接分析代码库高效工作流省去手工生成与上传文件的环节精简代码分析流程一致输出确保 AI 助手以一致、优化的格式获取代码库高级能力完整复用 Repomix 的代码压缩、token 计数与安全检查等全部能力。配置完成后你的 AI 助手即可直接调用 Repomix 的能力分析代码库让代码分析工作流更加高效。典型的使用闭环是先pack_codebase打包并拿到outputId→ 用grep_repomix_output定位关键符号 → 用read_repomix_output按行区间读取相关片段全程无需 Agent 直接触碰文件系统。相关资源Claude Code 插件 — Claude Code 的便捷插件集成配置指南 — 定制 Repomix 行为含output.patterns完整说明命令行选项 — 完整 CLI 参考输出格式 — 了解可用输出格式MCP 服务器源码mcpServer.ts、pathScope.ts、工具实现测试参考sandbox.contract.test.ts、packCodebaseTool.test.ts【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考