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 的 MCPModel Context Protocol服务能力为核心讲解如何将 Repomix 作为 MCP Server 启动、通过--sandbox沙箱模式隔离不可信客户端、在 VS Code / Cline / Cursor / Claude Desktop / Claude Code 中完成配置并逐个解析pack_codebase、pack_remote_repository、read_repomix_output、grep_repomix_output与两个 filesystem 工具的完整参数与用法。读完本文你将掌握一套AI 助手直接打包、检索、阅读本地或远程代码库的实战方案并理解其底层实现与安全边界。一、Repomix MCP Server 是什么Model Context Protocol (MCP) 是一种开放的客户端—服务器协议用于让 AI 助手与外部工具、数据源标准化交互。Repomix 支持该协议当它以--mcp标志运行时会启动一个 MCP Server向兼容的 AI 助手暴露一组工具使其能够直接打包本地或远程仓库并进行分析无需任何手工准备文件。从 src/mcp/mcpServer.ts 的实现可以看出服务端启动时会把能力说明注入给模型Repomix MCP Server provides AI-optimized codebase analysis tools. Use pack_codebase or pack_remote_repository to consolidate code into a single XML file, use generate_skill to create Claude Agent Skills from codebases, use attach_packed_output to work with existing packed outputs, then read_repomix_output and grep_repomix_output to analyze it. Perfect for code reviews, documentation generation, bug investigation, GitHub repository analysis, and understanding large codebases. Scans for known secret formats and supports compression for token efficiency.[!NOTE] 这是 Repomix 的实验性功能官方会基于用户反馈与实际使用持续改进。二、快速启动把 Repomix 运行为 MCP Server启动 MCP 模式只需一个命令repomix --mcp该命令会让 Repomix 进入 MCP Server 模式通过stdio通道与支持 MCP 的 AI 助手通信。在 src/cli/cliRun.ts 中--mcp与--sandbox [dir]是相邻声明的两个选项.option(--mcp, Run as Model Context Protocol server for AI tool integration) .option( --sandbox [dir], With --mcp: confine the MCP servers file tools to a workspace directory (defaults to the working directory; ...), )当检测到--mcp时CLI 会动态加载 src/cli/actions/mcpAction.ts 中的runMcpAction最终调用runMcpServer见 src/mcp/mcpServer.ts服务端名称为repomix-mcp-server版本取自package.json传输层使用StdioServerTransport进程监听SIGINT/SIGTERM优雅关闭后再退出避免残留输出文件或半成品状态。三、Sandbox 沙箱模式为不可信客户端准备的路径隔离默认情况下MCP Server 可以读取宿主用户可访问的任何路径。这对可信的本地助手很方便但当服务器暴露给不可信客户端或 Agent 时范围就过大了。--sandbox标志将服务器的文件工具限制在单一 workspace 目录内# 限制到当前工作目录 repomix --mcp --sandbox # 限制到指定目录 repomix --mcp --sandbox path/to/project沙箱模式下的路径规则所有路径都相对 workspace root 解释。绝对路径、~、..以及 Windows 的盘符/UNC 路径一律被拒绝指向 root 之外包括经 symlink 逃逸的路径会被丢弃。结果与错误信息同样是相对路径不会暴露宿主路径。这一规则同时适用于下述工具的directory与path参数——在沙箱模式下请始终给出相对于 workspace root 的路径而不是表格中描述的绝对路径形式。上述规则在 src/mcp/pathScope.ts 中有完整实现isEscapingPath判定绝对路径 / 盘符相对路径如C:foo/~与~// 任何..段均为逃逸resolveWithinRoot在词法约束之外还会通过realpath解析 symlink捕获 root 内指向 root 外部的链接toVirtualPath把结果转换为src/x.ts形式的虚拟路径返回给客户端。沙箱模式下注册的工具变化仅注册受限的只读工具pack_codebase、read_repomix_output、grep_repomix_output、file_system_read_file、file_system_read_directory。远程打包、Skill 生成、外部输出附加被禁用因为它们分别访问网络、写文件、或引用任意路径见 src/mcp/mcpServer.ts。两个file_system_*工具只在沙箱模式下注册因为只有 workspace root 能约束它们的可达范围非沙箱模式下它们根本不会被注册。需要特别强调的是这是应用层的工具表面限制纵深防御而非操作系统级沙箱。当面向不可信客户端托管服务器时仍然应当在平台级隔离环境容器、专用用户中运行。另外--sandbox只影响 MCP Server没有--mcp时它不产生任何效果src/cli/cliRun.ts 会打印警告并忽略。沙箱下的额外加固从 src/mcp/tools/packCodebaseTool.ts 可以看到沙箱模式下打包时还会叠加一组内部隔离参数...(config.sandboxed ? { skipLocalConfig: true, skipGlobalConfig: true, confineToBaseDir: true, gitSortByChanges: false } : {}),skipLocalConfig/skipGlobalConfig跳过仓库内的repomix.config.*和操作员的全局配置——防止配置驱动的output.instructionFilePath把 workspace 外的文件读入模型可见输出或input.processors执行命令confineToBaseDir作为语法无关的兜底丢弃任何解析到 root 之外的文件即使 include/ignore 模式用了无法静态展开的 extglob 语法gitSortByChanges: false禁用基于 git 的排序sortByChanges默认开启时会在不可信的.git/config上执行git log存在命令执行面。同时includePatterns/ignorePatterns会经过patternsEscapeRoot预检——先用 brace 展开拆解{/etc/**,x}这类可走私绝对路径的写法再拒绝逃逸模式给出可读的报错。四、在主流 AI 客户端中配置 MCP Server要把 Repomix 作为 MCP Server 接入 Claude 等 AI 助手需要配置 MCP 设置。以下各节覆盖主流客户端。4.1 VS Code方式一点击 VS Code 安装徽章vscode:mcp/install协议一键注册名为repomix、命令为npx -y repomix --mcp的服务器VS Code Insiders 使用vscode-insiders:mcp/install。方式二命令行注册code --add-mcp {name:repomix,command:npx,args:[-y,repomix,--mcp]}VS Code Insiderscode-insiders --add-mcp {name:repomix,command:npx,args:[-y,repomix,--mcp]}4.2 ClineVS Code 扩展编辑cline_mcp_settings.json{ mcpServers: { repomix: { command: npx, args: [ -y, repomix, --mcp ] } } }4.3 Cursor在 Cursor 中进入Cursor SettingsMCP Add new global MCP server使用与 Cline 类似的配置即可。4.4 Claude Desktop编辑claude_desktop_config.json使用与 Cline 类似的mcpServers结构。4.5 Claude Code在 Claude Code 中通过一条命令完成注册claude mcp add repomix -- npx -y repomix --mcp此外还可以使用官方 Repomix Claude Code 插件获得更顺手的体验——插件提供自然语言命令与更简单的配置详见 Plugin Claude Code。4.6 用 Docker 替代 npx不想依赖 npx 时可用官方 Docker 镜像运行 MCP Server{ mcpServers: { repomix-docker: { command: docker, args: [ run, -i, --rm, ghcr.io/yamadashy/repomix, --mcp ] } } }-i保持 stdin 打开以承载 stdio 通信--rm在容器退出后自动清理。五、MCP Tools 详解5.1 pack_codebase — 打包本地代码库将本地代码目录打包为单个 AI 分析文件分析代码库结构、提取相关代码内容生成包含指标、文件树、格式化代码内容的综合报告。参数参数必填默认值说明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 }。首个匹配的模式生效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/下的文件只出现在目录结构中其余文件被压缩。从源码看pack_codebase本质上是把参数翻译为CliOptions后调用runCli见 src/mcp/tools/packCodebaseTool.tsstyle直接决定输出文件名repomix-output.xml/.md/.json/.txt并返回outputId、outputFilePath、totalFiles、totalTokens、directoryStructure等结构化结果供后续工具引用。5.2 pack_remote_repository — 打包远程 GitHub 仓库拉取、克隆并打包 GitHub 仓库为单个分析文件自动完成克隆、结构分析与综合报告生成。参数参数必填默认值说明remote是—GitHub 仓库 URL 或user/repo格式如yamadashy/repomix、https://github.com/user/repo、https://github.com/user/repo/tree/branchcompress否false同pack_codebaseTree-sitter 压缩约省 70% tokenincludePatterns否—fast-glob 包含模式逗号分隔ignorePatterns否—fast-glob 排除模式逗号分隔outputPatterns否—逐文件包含级别语义同pack_codebasetopFilesLength否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 }该工具在回显仓库元数据前会调用redactUrl见 src/mcp/tools/packRemoteRepositoryTool.ts若 remote URL 携带凭据返回给模型的内容会被脱敏避免凭据残留在 MCP 对话记录、客户端日志与模型上下文中。5.3 read_repomix_output — 按 ID 读取打包输出读取 Repomix 生成的输出文件内容支持按行区间部分读取大文件。设计目标是在直接文件系统访问受限的环境中如 Web 环境、沙箱应用也能拿到打包后的代码库。参数参数必填默认值说明outputId是—要读取的 Repomix 输出文件 IDstartLine否文件开头起始行号从 1 开始含endLine否文件结尾结束行号从 1 开始含特性专为 Web / 沙箱类受限环境设计通过输出 ID 取回先前生成的输出内容无需文件系统访问即可提供打包后的代码库对大文件支持部分读取。示例{ outputId: 8f7d3b1e2a9c6054, startLine: 100, endLine: 200 }实现上src/mcp/tools/readRepomixOutputTool.ts输出文件注册在内存 registry 中见 src/mcp/tools/mcpToolRuntime.ts 的outputFileRegistry按outputId查表得到路径行号会做合法性校验startLine 1、startLine endLine、不得超出总行数对于从未受信任路径附加的输出返回内容前会先跑 Secretlint 扫描。5.4 grep_repomix_output — 在打包输出中 grep在 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 }从源码看src/mcp/tools/grepRepomixOutputTool.ts搜索实现先把内容拆成行数组逐行用RegExp(pattern, g | gi)匹配再按上下文窗口生成带行号:/行号-前缀与--分隔符的格式化输出无效正则会被捕获并返回明确错误输出会包含matches、totalMatches、formattedOutput等字段。5.5 file_system_read_file 与 file_system_read_directory — 沙箱内文件访问这两个 filesystem 工具只在--sandbox模式下注册见 src/mcp/mcpServer.tsworkspace root 约束其可达范围没有--sandbox时它们不会出现在工具列表中。file_system_read_file读取相对 workspace root 的文件内容如src/index.ts对匹配已知 secret 格式的内容予以拒绝基于 Secretlint 的启发式防护真正的访问边界是 workspace root而不是该扫描对无效路径返回清晰错误且不暴露宿主路径。file_system_read_directory列出相对 workspace root 的目录内容如.或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 助手需要以下能力时非常有用分析 workspace 中的特定文件遍历目录结构验证文件的存在性与可访问性。六、源码级原理错误处理与安全边界沙箱模式下的错误处理采用了白名单式泄漏防护设计src/mcp/tools/mcpToolRuntime.ts 的sandboxErrorReason绝不把error.message原样转发给模型它可能嵌入 workspace root、Repomix 安装路径、Node 运行时路径或操作员家目录而是仅依据错误码映射为固定原因——ENOENT→not found、EACCES/EPERM→permission denied、ELOOP→too many symbolic links 等只有PathScopeError例外因为它的消息只由 Agent 自己的输入与路径规则构成是安全且有价值的。完整错误仍会通过logger.error写入操作员的 stderr。另外值得注意非沙箱模式下file_system_*工具要求绝对路径沙箱模式下则要求相对路径且经resolveWithinRoot约束后回显虚拟路径——同一工具的两种契约在 fileSystemReadFileTool.ts 与 fileSystemReadDirectoryTool.ts 中由config.sandboxed分支实现。七、使用 Repomix 作为 MCP Server 的收益直接集成AI 助手可以直接分析代码库无需手工准备文件高效工作流省去手动生成、上传文件的环节简化代码分析流程一致输出助手拿到的是格式统一、经过优化的代码库呈现高级能力完整继承 Repomix 的代码压缩、token 统计、安全扫描含 Secretlint等特性。配置完成后你的 AI 助手即可直接调用 Repomix 的能力分析代码库让代码分析工作流显著更高效。八、相关资源Claude Code 插件 — 面向 Claude Code 的便捷插件集成配置指南 — 自定义 Repomix 行为命令行选项 — 完整的 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），仅供参考