Repomix MCP Server: Running Your Codebase as a Model Context Protocol Server for AI Assistants【免费下载链接】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服务器形式运行的完整实战指南。它面向希望让 Claude、ChatGPT、Gemini 等 AI 助手直接对本地或远程代码仓库执行打包、检索与读取的开发者通过--mcp与--sandbox两个核心标志、六大 MCP 工具的完整参数表、以及 VS Code / Cline / Cursor / Claude Desktop / Claude Code / Docker 的全套客户端配置方案你将能够在几分钟内把 Repomix 接入主流 AI 编程环境省去手动生成并上传文件的工作并获得源码级的原理认知。[!NOTE] 这是一个实验性功能experimental featureRepomix 团队将根据用户反馈和真实世界使用情况持续改进。本文所有命令与参数均以当前仓库实际实现为准。Repomix 为什么需要 MCP 服务器模式Repomix 的核心能力是把整个仓库打包成单一、AI 友好的文件XML / Markdown / JSON / Plain。在传统工作流中你需要先在终端运行repomix生成文件再把文件喂给 LLM。而 MCP 服务器模式改变了这一交互方式AI 助手可以在对话中直接调用工具完成打包 → 读取 → 搜索的闭环不需要任何人工文件准备。从源码看MCP 服务器在启动时会把自身能力描述注入给客户端。在 src/mcp/mcpServer.ts 中服务器指令instructions明确写道Usepack_codebaseorpack_remote_repositoryto consolidate code into a single XML file, usegenerate_skillto create Claude Agent Skills from codebases, useattach_packed_outputto work with existing packed outputs, thenread_repomix_outputandgrep_repomix_outputto analyze it. Perfect for code reviews, documentation generation, bug investigation, GitHub repository analysis, and understanding large codebases.也就是说MCP 模式把 Repomix 的整条打包分析流水线含压缩、Token 计数、安全检查变成了 AI 助手可以直接触达的标准工具面。将 Repomix 作为 MCP 服务器运行启动方式非常简单只需要--mcp标志repomix --mcp该命令会让 Repomix 进入 MCP 服务器模式通过标准输入/输出stdio与支持 Model Context Protocol 的 AI 助手通信。从源码调用链看--mcp由 src/cli/actions/mcpAction.ts 处理最终进入 src/mcp/mcpServer.ts 的runMcpServer通过StdioServerTransport建立传输通道new StdioServerTransport()后server.connect(transport)监听SIGINT/SIGTERM信号触发server.close()优雅关闭关闭失败时以退出码 1 结束服务器元数据包括name: repomix-mcp-server与通过getVersion()读取的包版本号。--mcp标志定义在 src/cli/types.ts 的CliOptions中mcp?: boolean; sandbox?: boolean | stringsandbox同时支持布尔值或目录字符串——这正是下一节两种沙盒写法的来源。沙盒模式Sandbox Mode限制文件工具的作用域为什么需要沙盒默认情况下MCP 服务器可以读取宿主用户可读的任何路径。这对于可信的本地助手很方便但当服务器暴露给不可信客户端或 Agent 时权限就过宽了。--sandbox标志将服务器的文件工具限制在单一工作区目录内# 限制到当前工作目录 repomix --mcp --sandbox # 限制到指定目录 repomix --mcp --sandbox path/to/project沙盒开启后的两条核心规则1. 每个路径都相对于工作区根目录workspace root。绝对路径、~家目录引用、..穿越段、以及 Windows 盘符 / UNC 路径都会被拒绝解析后越出根目录的路径包括通过符号链接 symlink 逃逸会被丢弃返回的结果与错误消息同样是相对路径从而不暴露宿主机的任何路径信息。该规则同样适用于下方工具参考中的directory与path参数在沙盒模式下请传入相对于工作区根目录的路径例如.、src、src/index.ts而不是表格中通常描述的绝对路径。从源码层面看这一整套检查实现在 src/mcp/pathScope.tsisEscapingPath()拒绝四类输入path.isAbsolute判定的绝对路径Windows 盘符相对路径如C:foopath.isAbsolute会漏掉这种形式~与~/家目录引用以及任何..穿越段无论正斜杠还是反斜杠分隔。注释特别说明仅以~开头的普通文件名如~$lock.docx是允许的只有家目录引用形式才被拒绝resolveWithinRoot()在词法解析后先用isInside()校验候选路径必须位于根内再通过realpath解析真实路径捕获根内链接指向根外的 symlink 逃逸若目标尚不存在导致 realpath 失败则回退到已经过词法约束的路径toVirtualPath()把根内绝对路径转换为根相对路径根自身表示为.供结果显示使用避免宿主路径外泄。2. 只注册只读、根受限的工具。沙盒模式下仅注册pack_codebase、read_repomix_output、grep_repomix_output、file_system_read_file、file_system_read_directory。远程打包pack_remote_repository、技能生成generate_skill与外部输出附加attach_packed_output会被禁用因为它们要么访问网络、要么写入文件、要么引用任意路径。而两个file_system_*工具本身也只在沙盒模式下才注册见 src/mcp/mcpServer.ts 中if (config.sandboxed)分支——工作区根目录限定了它们可达的范围。沙盒是纵深防御不是操作系统级沙箱文档与源码都强调这是对工具面的应用层限制defense in depth并非 OS 级沙箱。当为不可信客户端托管服务器时仍应将其运行在平台常规隔离手段之下容器、专用用户等。另外需要注意--sandbox只影响 MCP 服务器没有--mcp时它不产生任何效果。沙盒模式下的额外加固源码细节阅读 src/mcp/tools/packCodebaseTool.ts 可以看到沙盒模式为pack_codebase额外附加了多项加固include/ignore 模式越权检查patternsEscapeRoot()用与打包器相同的 brace-aware 分词splitPatterns加 brace 展开braceExpand逐 token 检查——防止{/etc/**,x}这类花括号备选项走私绝对路径也剥离前导!取反符后再检查强制跳过配置文件skipLocalConfig: true, skipGlobalConfig: true——因为工作区的repomix.config.*或操作者的全局配置可能设置output.instructionFilePath把工作区外的文件读进 Agent 可见输出或通过input.processors执行命令强制限制文件搜索范围confineToBaseDir: true作为语法无关的兜底丢弃任何解析到根目录之外的文件禁用 git 排序gitSortByChanges: false——默认开启的sortByChanges会执行git -C workspace log从而读取不可信工作区的.git/config例如log.showSignature触发的gpg.program这是宿主命令执行向量错误消息白名单src/mcp/tools/mcpToolRuntime.ts 的sandboxErrorReason()只根据错误码ENOENT→ not found、EACCES/EPERM→ permission denied 等枚举映射生成固定原因绝不转发error.message——因为原始消息可能内嵌工作区根、Repomix 安装路径、Node 运行时或操作者家目录等宿主路径。配置 MCP 服务器主流 AI 客户端接入指南要配合 Claude 等 AI 助手使用需要为客户端配置 MCP 服务器。以下配置均可直接复制使用。VS Code可以通过两种方式安装使用安装徽章文档中的 Install in VS Code / Install in VS Code Insiders 徽章触发的是vscode:mcp/install协议其底层等价于注册一个名为repomix、命令为npx、参数为[-y, repomix, --mcp]的 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添加新服务器配置与上述 Cline 配置一致。Claude Desktop编辑claude_desktop_config.json采用与 Cline 配置相同的结构mcpServers下注册repomix条目。Claude Code使用以下命令直接注册claude mcp add repomix -- npx -y repomix --mcp此外还可以使用官方 Repomix 插件获得更便捷的体验插件提供自然语言命令和更简单的设置流程详见 Claude Code 插件文档。使用 Docker 替代 npx不想依赖 npx 时可以用 Docker 运行 Repomix MCP 服务器ghcr.io/yamadashy/repomix镜像{ mcpServers: { repomix-docker: { command: docker, args: [ run, -i, --rm, ghcr.io/yamadashy/repomix, --mcp ] } } }注意这里使用-i保持标准输入打开与--rm容器退出即清理因为 MCP 服务器通过 stdio 通信。可用 MCP 工具详解当以 MCP 服务器运行时Repomix 提供以下工具。所有工具的输入输出 Schema 均由 Zod 定义于各工具源文件中下面参数表与源码实现一一对应。pack_codebase将本地代码目录打包为单一文件默认 XML供 AI 分析。它分析代码库结构、提取相关代码内容并生成包含指标metrics、文件树file tree和格式化代码内容的综合报告。实现见 src/mcp/tools/packCodebaseTool.ts核心逻辑是构造CliOptions后调用runCli([.], targetDirectory, cliOptions)复用完整的 CLI 打包管线。参数参数必填默认值说明directory是—要打包的目录。非沙盒模式传绝对路径沙盒模式传相对于工作区根目录的路径如.或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 }条目组成的数组。首个匹配的 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/下的文件仅出现在目录结构中其余一切被压缩。返回结构源码佐证工具返回description、result含指标与文件信息的 JSON 字符串、directoryStructure目录树、outputId访问打包内容的唯一标识、outputFilePath、totalFiles与totalTokens。其中outputId由 src/mcp/tools/mcpToolRuntime.ts 的内存注册表outputFileRegistry维护registerOutputFile/getOutputFilePath供后续read_repomix_output、grep_repomix_output检索文件路径使用。打包产物落在 Repomix 的临时工作目录createToolWorkspace()因此这些工具特别适合文件系统访问受限的环境。pack_remote_repository自动 clone 一个 GitHub 远程仓库并打包为单一 XML 文件供 AI 分析。它分析仓库结构并生成综合报告。实现见 src/mcp/tools/packRemoteRepositoryTool.ts。参数参数必填默认值说明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 模式指定要包含的文件逗号分隔如**/*.{js,ts}、src/**,docs/**ignorePatterns否—用 fast-glob 模式额外排除文件逗号分隔如test/**,*.spec.js是对.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 }安全细节源码佐证工具回显的远程地址会经过redactUrl()脱敏见 src/shared/urlRedact.ts——否则带凭据的远程地址会残留在 MCP 对话记录、客户端日志与模型上下文中。该工具标注为openWorldHint: true且仅在非沙盒模式下注册需要网络访问。read_repomix_output读取 Repomix 生成的输出文件内容支持用行范围指定对超大文件做部分读取。该工具专为直接文件系统访问受限的环境如 Web 环境、沙盒应用设计。实现见 src/mcp/tools/readRepomixOutputTool.ts。参数参数必填默认值说明outputId是—要读取的 Repomix 输出文件 IDstartLine否文件开头起始行号基于 1包含该行endLine否文件结尾结束行号基于 1包含该行特性专为 Web 环境或沙盒应用设计通过 ID 检索此前生成过的输出内容无需文件系统访问即可读取已打包代码库对大型文件支持部分读取。示例{ outputId: 8f7d3b1e2a9c6054, startLine: 100, endLine: 200 }源码细节行号采用 1-based 且包含两端源码中会校验startLine 1、endLine 1、startLine endLine、起始行不超出文件总行数。对于从不可信路径附加的输出文件requiresSecretScan每次提供内容前都会先运行 Secretlint 检查runSecretLint发现疑似敏感信息即拒绝返回——这是启发式防护不是访问边界。grep_repomix_output用 grep 式功能在 Repomix 输出文件中检索模式语法为 JavaScript RegExp返回匹配行及可选的上下文行。实现见 src/mcp/tools/grepRepomixOutputTool.ts。参数参数必填默认值说明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 }源码细节匹配流程由createRegexPatternignoreCase时使用gi标志非法正则抛出带原因的错误、searchInLines逐行line.match(regex)记录行号、整行内容与匹配文本、formatSearchResults生成行号:精确匹配与行号-上下文行的 grep 风格输出并在上下文区间出现空隙时插入--分隔符组成。为优化 3–5MB 大输出文件的处理performGrepSearch只对内容做一次 split 并复用行数组。file_system_read_file 与 file_system_read_directory这两个文件系统工具仅在沙盒模式--sandbox下可用此时工作区根目录限定了它们的可达范围没有--sandbox时它们不会被注册见 src/mcp/mcpServer.ts。实现见 src/mcp/tools/fileSystemReadFileTool.ts 与 src/mcp/tools/fileSystemReadDirectoryTool.ts。file_system_read_file读取相对于工作区根目录的路径上的文件内容如src/index.ts会拒绝匹配已知敏感信息格式Secretlint 识别 API 密钥、密码等的内容作为额外的启发式安全防护——访问边界是工作区根目录而不是扫描本身对无效路径返回清晰的错误消息且不暴露宿主路径。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 助手需要以下能力时这两个工具尤为有用分析工作区中的特定文件在目录结构中导航确认文件的存在性与可访问性。使用 Repomix 作为 MCP 服务器的优势直接集成AI 助手无需手动准备文件即可直接分析你的代码库高效工作流省去手动生成并上传文件的步骤精简代码分析流程一致输出确保 AI 助手以统一、优化的格式获取代码库高级特性完整复用 Repomix 的全部能力包括代码压缩、Token 计数与安全检查。一旦配置完成你的 AI 助手就能直接调用 Repomix 的能力来分析代码库让代码分析工作流变得更高效。典型工作流从源码与测试推断的推荐用法沙盒安全探索先用file_system_read_directory .摸清工作区结构再用file_system_read_file细读关键文件需要整体分析时调用pack_codebase .生成打包产物最后用grep_repomix_output以增量方式检索特定符号——这种先探索、再打包、后检索的组合可以最大化 Token 效率也正是compress参数注释中通常不需要因为grep_repomix_output允许增量内容检索所对应的用法远程仓库分析直接调用pack_remote_repository传入user/repo或完整 URL随后用read_repomix_output配合startLine/endLine分批阅读大文件避免一次性消耗过多上下文。上述工具行为均有对应测试覆盖例如 tests/mcp/mcpServer.test.ts、tests/mcp/tools/sandbox.contract.test.ts、tests/mcp/tools/fileSystemReadFileTool.sandbox.test.ts 等可进一步阅读以验证沙盒路径规则、工具注册条件与错误白名单机制。相关资源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），仅供参考