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 Protocol (MCP) 编写结合 MCP 服务端实现 及其工具源码系统讲解启动方式、沙箱模式、各 AI 客户端配置方法与全部工具参数读完即可在自己的工作流中落地使用。[!NOTE] MCP Server 属于实验性功能官方会根据用户反馈和真实使用场景持续改进。快速开始以 MCP Server 模式启动 Repomix在项目目录下使用--mcp标志即可将 Repomix 启动为 MCP Serverrepomix --mcp该命令使 Repomix 进入 MCP Server 模式通过标准输入输出stdio与支持 Model Context Protocol 的 AI 助手通信。从源码看CLI 的 mcpAction.ts 会调用 runMcpServer后者基于modelcontextprotocol/sdk创建名为repomix-mcp-server的服务器实例并连接StdioServerTransport传输层同时注册SIGINT/SIGTERM信号处理以优雅关闭服务器。启动后Repomix 会根据运行模式注册不同工具集合详见下文沙箱模式与MCP 工具参考AI 助手即可调用pack_codebase打包代码、用read_repomix_output/grep_repomix_output增量读取与检索打包结果。Sandbox 沙箱模式默认情况下MCP Server 可以读取宿主用户可读的任何路径。这对受信任的本地助手很方便但当服务器暴露给不受信任的客户端或 Agent 时范围过宽。--sandbox标志可将服务器的文件工具限定在单一工作区目录内# 限定到当前工作目录 repomix --mcp --sandbox # 限定到指定目录 repomix --mcp --sandbox path/to/project需要特别说明--sandbox只影响 MCP Server不与--mcp一起使用时没有任何效果。沙箱模式的路径规则开启沙箱模式后所有路径都相对于工作区根目录。绝对路径、~、..以及 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:fooresolveWithinRoot在词法解析后还会通过fs.realpath解析符号链接拦截根内链接指向根外的逃逸toVirtualPath负责把根内绝对路径转换为根相对路径根目录本身显示为.从而保证返回结果不暴露宿主路径。工具注册白名单mcpServer.ts 按sandboxed标志分流——pack_codebase、read_repomix_output、grep_repomix_output始终注册两个文件系统工具仅在沙箱模式注册而pack_remote_repository、generate_skill、attach_packed_output需要网络/写文件/引用任意路径仅在非沙箱模式注册。服务器指令instructions也随之切换为沙箱专用版本只向 Agent 描述可用工具与路径规则。打包时的额外加固在 packCodebaseTool.ts 中沙箱模式下打包会附加一组锁定参数skipLocalConfig跳过目标仓库的repomix.config.*、skipGlobalConfig跳过操作者全局配置防止配置中的output.instructionFilePath把工作区外文件读入 Agent 可见输出、confineToBaseDir语法无关的逃逸兜底丢弃任何解析到根目录之外的文件、gitSortByChanges: false禁用基于 git log 的排序避免执行不受信任工作区.git/config中的命令例如gpg.program。此外patternsEscapeRoot会对 include/ignore 模式做 brace 展开检查阻止{/etc/**,x}这类把绝对路径夹带进 glob 的尝试。错误信息防泄漏mcpToolRuntime.ts 的sandboxErrorReason是错误信息的白名单——它只根据错误码如ENOENT→not found、EACCES→permission denied生成固定原因并拼接 Agent 自己传入的输入绝不转发原始error.message其中可能嵌入工作区根路径、安装路径或家目录从结构上保证宿主路径不会到达不受信任的 Agent。在主流 AI 客户端中配置 Repomix MCP Server要在 Claude 等 AI 助手中使用 Repomix MCP Server需要配置对应客户端的 MCP 设置。VS CodeVS Code 支持两种安装方式使用安装徽章文档中提供了Install ServerVS Code与Install ServerVS Code Insiders两个安装徽章点击即可一键安装名为repomix、命令为npx -y repomix --mcp的 MCP Server。使用命令行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 Server配置方式与 Cline 类似。Claude Desktop编辑claude_desktop_config.json文件配置方式与 Cline 类似。Claude Code在 Claude Code 中通过以下命令添加claude mcp add repomix -- npx -y repomix --mcp另外也可以使用官方 Repomix 插件获得更便捷的体验——插件提供自然语言命令和更简单的配置详见 Claude Code Plugins。使用 Docker 替代 npx除 npx 外也可以用 Docker 运行 Repomix MCP Server{ mcpServers: { repomix-docker: { command: docker, args: [ run, -i, --rm, ghcr.io/yamadashy/repomix, --mcp ] } } }MCP 工具参考以 MCP Server 模式运行时Repomix 提供以下工具沙箱模式只注册其中受根目录约束的部分。pack_codebase打包本地代码目录生成用于 AI 分析的合并文件默认 XML。该工具会分析代码库结构、提取相关代码内容并生成包含指标、文件树和格式化代码内容的综合报告。参数参数必填默认值说明directory是—要打包目录的绝对路径沙箱模式下为相对于工作区根目录的路径compress否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 }。首个匹配的 pattern 生效directoryStructureOnly优先于compress两者都不带的匹配会强制保留完整内容可用于把特定文件从全局compress中豁免。会覆盖目标仓库repomix.config.json中的output.patternstopFilesLength否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 使用 zod 对参数做校验topFilesLength要求为正整数style限定为四种枚举值。工具内部会创建临时工作区createToolWorkspace、调用 CLI 核心的runCli执行打包始终开启securityCheck安全扫描随后通过 mcpToolRuntime.ts 的formatPackToolResponse生成outputId并注册到输出文件注册表供后续读取/检索工具使用。pack_remote_repository获取、克隆并打包 GitHub 远程仓库生成用于 AI 分析的合并文件。该工具自动克隆远程仓库、分析其结构并生成综合报告。参数参数必填默认值说明remote是—GitHub 仓库 URL 或user/repo格式如yamadashy/repomix、https://github.com/user/repo、https://github.com/user/repo/tree/branchcompress否false同pack_codebase的compress启用 Tree-sitter 压缩可减少约 70% 的 token 消耗includePatterns否—同pack_codebasefast-glob 包含模式逗号分隔ignorePatterns否—同pack_codebasefast-glob 排除模式逗号分隔outputPatterns否—同pack_codebase按文件设置包含级别对应output.patternstopFilesLength否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 }实现细节上packRemoteRepositoryTool.ts 通过runCli携带--remote参数完成克隆与打包值得注意的是返回结果中的仓库地址会经过redactUrl脱敏处理见src/shared/urlRedact.ts避免带凭据的远程地址残留在 MCP 对话记录、客户端日志与模型上下文中。read_repomix_output读取 Repomix 生成的输出文件内容支持通过行范围对超大文件进行部分读取。该工具专为文件系统访问受限的环境设计。参数参数必填默认值说明outputId是—要读取的 Repomix 输出文件 IDstartLine否文件开头起始行号从 1 开始含endLine否文件结尾结束行号从 1 开始含特性专为基于 Web 的环境或沙箱应用设计使用输出 ID 检索此前生成的内容无需文件系统访问即可读取打包后的代码库支持大文件的部分读取示例{ outputId: 8f7d3b1e2a9c6054, startLine: 100, endLine: 200 }源码层面的细节readRepomixOutputTool.ts 先从注册表按outputId解析文件路径再对startLine/endLine做严格校验均为正整数、startLine不得大于endLine、起始行不得超出文件总行数。对于从不受信任路径附加的输出文件读取前会执行 Secretlint 安全扫描命中已知敏感格式即拒绝返回内容。grep_repomix_output在 Repomix 输出文件中搜索模式采用 grep 风格并结合 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 将performGrepSearch拆分为searchInLines逐行正则匹配gi/g标志切换大小写与formatSearchResults生成带行号前缀的123:/123-格式输出并用--分隔不连续片段且只对内容做一次split(\n)避免在大输出文件数 MB 级上重复切分的性能开销。返回结果包含每个匹配的行号、整行内容与匹配文本。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 });这些工具在 AI 助手需要以下场景时尤其有用分析工作区中的特定文件浏览目录结构验证文件是否存在及可访问源码层面fileSystemReadFileTool.ts 在沙箱模式下通过resolveToolPath完成相对路径 → 根内绝对路径 → 虚拟显示路径的转换非沙箱模式则保留传统的绝对路径契约并在入口做前置校验。返回内容包含路径、内容、字节大小、编码与行数读取前同样执行 Secretlint 扫描。将 Repomix 作为 MCP Server 使用的收益直接集成AI 助手无需手动准备文件即可直接分析你的代码库。高效工作流省去手动生成与上传文件的环节简化代码分析流程。一致输出确保 AI 助手以一致、优化的格式获得代码库。高级特性充分发挥 Repomix 的代码压缩、token 计数与安全检查等全部能力。配置完成后你的 AI 助手就可以直接调用 Repomix 的能力分析代码库让代码分析工作流更高效。相关资源Claude Code PluginsClaude Code 的便捷插件集成Configuration自定义 Repomix 行为Command Line Options完整 CLI 参考Output Formats了解可用输出格式【免费下载链接】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），仅供参考