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 ProtocolMCP服务器能力展开说明如何将 Repomix 以--mcp模式作为 MCP 服务器运行使 Claude、ChatGPT、DeepSeek 等 AI 助手直接调用pack_codebase、read_repomix_output、grep_repomix_output等工具无需手动准备文件即可分析本地或远程仓库。读完本文你将掌握MCP 模式的启动方式、sandbox 沙箱模式的路径与工具约束、主流 AI 客户端VS Code、Cline、Cursor、Claude Desktop、Claude Code、Docker的完整接入配置以及每个 MCP 工具的详细参数与调用示例。[!NOTE] 这是 Repomix 的一项实验性功能官方会根据用户反馈和真实使用情况持续改进。Repomix 与 Model Context ProtocolRepomix 兼容 Model Context Protocol (MCP)这让 AI 助手能够直接与你的代码交互。当 Repomix 以 MCP 服务器运行时它会提供一组工具使 AI 助手可以直接打包本地或远程仓库用于分析而不需要用户手动准备文件、复制粘贴代码或上传压缩包——整个打包 → 交付给模型的流程完全自动化。从源码实现看MCP 服务器基于官方modelcontextprotocol/sdk构建createMcpServer创建McpServer实例名为repomix-mcp-server并通过StdioServerTransport以标准输入输出stdio与客户端通信见 src/mcp/mcpServer.ts。服务器在启动时还注入了描述自身能力的 instructions 文本指导 AI 助手如何组合使用这些工具在 sandbox 模式下会切换为一套受限的 instructions只提及沙箱内可用的工具与路径规则确保被禁用的工具远程打包、技能生成、附加外部输出对 Agent 不留任何痕迹。启动 MCP 服务器将 Repomix 作为 MCP 服务器运行只需使用--mcp选项repomix --mcp这会启动 Repomix 的 MCP 服务器模式使其对支持 Model Context Protocol 的 AI 助手可用。CLI 中该选项的定义见 src/cli/cliRun.ts其动作入口runMcpAction会以当前工作目录为根目录调用runMcpServer见 src/cli/actions/mcpAction.ts。服务器通过 stdio 传输协议工作启动后注册SIGINT/SIGTERM处理器以便优雅退出见 src/mcp/mcpServer.ts。Sandbox 沙箱模式为不可信客户端加锁默认情况下MCP 服务器可以读取宿主用户有权限访问的任何路径。这对可信的本地助手很方便但当服务器暴露给不可信的客户端或 Agent 时权限范围就过大了。--sandbox选项将服务器的文件工具限制在单一工作区目录内# 限制到当前工作目录 repomix --mcp --sandbox # 限制到指定目录 repomix --mcp --sandbox path/to/project路径规则启用 sandbox 模式后每个路径都相对于工作区根目录。绝对路径、~、..以及 Windows 的盘符/UNC 路径都会被拒绝解析后落在根目录之外包括通过符号链接逃逸的路径会被丢弃。结果和错误消息也是相对路径因此宿主机路径不会泄露。这适用于下文工具参考中的directory和path参数在 sandbox 模式下请传入相对工作区根目录的路径而不是表格在其他情况下描述的绝对路径。这条规则的底层实现在 src/mcp/pathScope.ts 中isEscapingPath负责静态识别绝对路径、C:盘符相对路径、~家目录引用、..穿越段resolveWithinRoot进一步通过realpath解析符号链接防止根目录内的链接指向根目录外。在 sandbox 模式下pack_codebase的includePatterns/ignorePatterns也会先经过patternsEscapeRoot的检查把花括号展开后仍会逃逸根目录的 glob如{/etc/**,x}提前拒绝见 src/mcp/tools/packCodebaseTool.ts。工具限制只注册限制在根目录内的只读工具pack_codebase、read_repomix_output、grep_repomix_output、file_system_read_file和file_system_read_directory。远程打包、技能生成和附加外部输出被禁用因为它们会访问网络、写文件或引用任意路径。两个file_system_*工具本身也只在 sandbox 模式下可用此时工作区根目录限定了它们能够到达的范围。这一点在 src/mcp/mcpServer.ts 中清晰可见三个只读打包/检索工具始终注册file_system_read_file与file_system_read_directory仅在config.sandboxed为 true 时注册而pack_remote_repository、generate_skill、attach_packed_output及远程仓库 prompt 仅在非 sandbox 模式下注册。安全边界说明需要强调的是这是应用层面对工具面的限制纵深防御而不是操作系统级沙箱。如果你将服务器托管给不可信客户端仍应在平台常规隔离容器、专用用户下运行。此外sandbox 模式下pack_codebase会额外跳过本地与全局配置文件防止output.instructionFilePath把工作区外的文件读进输出或input.processors执行命令、将文件搜索限定在根目录内、并关闭基于 git 的排序避免执行不可信工作区的git log触发gpg.program这类命令执行向量详细逻辑见 src/mcp/tools/packCodebaseTool.ts 中的注释说明。--sandbox只影响 MCP 服务器没有--mcp时它不生效。CLI 层面对此也有对应警告逻辑见 src/cli/cliRun.ts。错误信息不泄露主机路径sandbox 模式下所有工具的错误响应都经过buildSandboxErrorResponse统一构造错误消息只由白名单化的原因如not found、permission denied、path is a directory等基于错误码映射的固定枚举加上 Agent 自己输入的路径组成原始的error.message永远不被转发——因为其中可能嵌入工作区根目录、Repomix 安装路径、Node 运行时路径或操作者家目录。完整错误仍会通过logger.error输出到操作者的 stderr见 src/mcp/tools/mcpToolRuntime.ts。在主流 AI 客户端中配置 MCP 服务器要把 Repomix 作为 MCP 服务器与 Claude 等 AI 助手配合使用需要配置对应客户端的 MCP 设置。VS Code有两种方式在 VS Code 中安装 Repomix MCP 服务器使用安装徽章点击下方的 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 中配置 Repomix 为 MCP 服务器使用以下命令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 可用工具详解作为 MCP 服务器运行时Repomix 提供以下工具。所有工具实现均位于 src/mcp/tools/ 目录并通过 src/mcp/mcpServer.ts 注册。pack_codebase打包本地代码库该工具将本地代码目录打包成一个 XML 文件供 AI 分析。它分析代码库结构、提取相关代码内容并生成包含指标、文件树和格式化代码内容的完整报告。参数参数必填默认值说明directory是—要打包目录的绝对路径sandbox 模式下为相对工作区根目录的路径如.或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指标摘要中按大小展示的最大文件数量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/下的文件只在目录结构中列出其余文件全部压缩。从实现上看src/mcp/tools/packCodebaseTool.ts该工具本质上是把参数映射为CliOptions并调用内部的runCli完成打包同时强制开启securityCheck默认安全扫描工具会返回outputId、指标totalFiles、totalTokens、topFiles等、目录结构树以及一个 XML 结构样例供 AI 助手了解输出格式后按需用read_repomix_output分块读取。pack_remote_repository打包远程 GitHub 仓库该工具获取、克隆并打包一个 GitHub 仓库为 XML 文件供 AI 分析。它会自动克隆远程仓库、分析其结构并生成完整报告。参数参数必填默认值说明remote是—GitHub 仓库 URL 或user/repo格式如yamadashy/repomix、https://github.com/user/repo或https://github.com/user/repo/tree/branchcompress否false启用 Tree-sitter 压缩提取关键代码签名与结构、去除实现细节。可减少约 70% 的 token 用量并保留语义含义。通常不需要开启因为grep_repomix_output支持增量内容检索includePatterns否—使用 fast-glob 模式指定要包含的文件逗号分隔ignorePatterns否—使用 fast-glob 模式额外排除文件逗号分隔。补充.gitignore和内置排除规则outputPatterns否—按文件设置包含级别对应配置文件中的output.patterns选项语义同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 }注意该工具需要访问网络因此在 sandbox 模式下不可用见上文工具限制。read_repomix_output读取打包输出该工具读取 Repomix 生成的输出文件内容支持指定行范围的部分读取适用于大文件。它是为文件系统直接访问受限的环境如基于 Web 的环境、沙箱应用设计的。参数参数必填默认值说明outputId是—要读取的 Repomix 输出文件 IDstartLine否文件开头起始行号基于 1含该行endLine否文件结尾结束行号基于 1含该行特性专为基于 Web 或沙箱应用的环境设计通过 ID 检索之前生成的输出内容无需文件系统访问权限即可获取打包后的代码支持大文件的部分读取示例{ outputId: 8f7d3b1e2a9c6054, startLine: 100, endLine: 200 }实现细节src/mcp/tools/readRepomixOutputTool.tsoutputId通过内存中的输出注册表outputFileRegistry见 src/mcp/tools/mcpToolRuntime.ts映射到临时文件路径读取时会校验startLine ≥ 1、startLine ≤ endLine等边界条件。对于通过attach_packed_output从不可信路径附加的输出每次读取前还会运行 secretlint 扫描识别到已知密钥格式API key、密码等即拒绝返回内容sandbox 模式下错误消息不包含文件路径。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 }实现细节src/mcp/tools/grepRepomixOutputTool.ts搜索逻辑对内容只做一次按行拆分同时复用于匹配与格式化避免对 3–5MB 的大输出文件做重复的 O(n) 拆分格式化输出时对非匹配上下文行使用-前缀、匹配行使用:前缀与 grep 风格一致并在上下文出现断档时插入--分隔符。file_system_read_file 与 file_system_read_directory这两个文件系统工具只在 sandbox 模式--sandbox下可用此时工作区根目录限定了它们能到达的范围。没有--sandbox时它们不会被注册。1.file_system_read_file—— 读取文件读取相对于工作区根目录的路径下的文件内容如src/index.ts拒绝与已知密钥格式匹配的内容Secretlint作为额外的启发式防护访问边界是工作区根目录而非扫描本身对无效路径返回清晰的错误消息不暴露宿主机路径2.file_system_read_directory—— 列出目录列出相对于工作区根目录的目录内容如.或src用清晰的标识[FILE]或[DIR]展示文件和目录适合探索项目结构、理解代码库组织示例TypeScript 调用// 读取文件 const fileContent await tools.file_system_read_file({ path: src/index.ts }); // 列出目录内容 const dirContent await tools.file_system_read_directory({ path: src });这两个工具在 AI 助手需要以下能力时尤其有用分析工作区中的特定文件浏览目录结构验证文件是否存在、是否可访问实现细节src/mcp/tools/fileSystemReadFileTool.ts 与 src/mcp/tools/fileSystemReadDirectoryTool.ts非 sandbox 模式下它们要求绝对路径并原样回显保持旧版契约sandbox 模式下通过resolveToolPath把相对路径限制并虚拟化到根目录内展示。返回内容包含size、encoding、lines文件以及[FILE]/[DIR]条目列表、fileCount、directoryCount目录等结构化信息。使用 Repomix 作为 MCP 服务器的收益将 Repomix 作为 MCP 服务器使用能带来多项优势直接集成AI 助手无需手动准备文件即可直接分析你的代码。高效工作流消除了手动生成和上传文件的步骤简化代码分析流程。一致输出确保 AI 助手以一致、优化的格式接收代码。高级功能充分利用 Repomix 的全部能力如代码压缩Tree-sitter、token 计数和安全检查。配置完成后你的 AI 助手可以直接调用 Repomix 的能力来分析代码库使代码分析工作流更加高效。推荐的典型流程是先用pack_codebase或pack_remote_repository打包再根据返回的outputId用grep_repomix_output定位目标代码片段最后用read_repomix_output按行范围读取具体内容——既避免一次性消耗过多 token又能精确定位需要分析的代码。延伸阅读Claude Code 插件指南 —— Claude Code 的便捷插件集成配置指南 —— 自定义 Repomix 行为命令行选项 —— CLI 完整参考含--mcp、--sandbox定义输出格式 —— 了解可用的输出格式如果你想深入源码理解 MCP 服务器的内部机制可重点阅读 src/mcp/mcpServer.ts工具注册与沙箱分支、src/mcp/pathScope.ts路径限制核心逻辑、src/mcp/tools/mcpToolRuntime.ts输出注册表、错误白名单化与响应构造以及 src/mcp/tools/ 下的各工具实现与对应的 测试用例。【免费下载链接】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），仅供参考