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.tsisEscapingPath拒绝绝对路径、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]}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 ] } } }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/branchcompress否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 输出文件 IDstartLine否文件开头起始行号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 输出文件 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。内容先按行切分一次避免对 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区分文件/目录读取后通过createSecretLintConfigrunSecretLint做敏感信息扫描命中则拒绝返回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 则覆盖了根目录逃逸拦截等路径边界用例。相关资源Claude Code 插件指南Claude Code 的便捷插件集成配置指南自定义 Repomix 行为含output.patterns的配置说明命令行选项参考完整 CLI 参考输出格式指南了解可用的输出格式【免费下载链接】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），仅供参考