Repomix MCP Server 安装与配置完全指南：让 Cline、Claude Desktop、Cursor 直接打包与分析代码库

本指南以 Repomix 官方 MCP 服务器安装文档为主体，面向 Cline、Roo Code、Claude Desktop、Cursor 等 LLM 客户端与 AI Agent，完整讲解 Repomix MCP Server 的安装前置条件、配置文件位置、五类核心工具的用法与参数，并结合仓库源码剖析其底层实现原理。读完本文，你将掌握如何在自己的 AI 开发环境中一键接入 Repomix，让助手无需手动准备文件即可直接打包本地或远端代码库、检索打包结果并进行高效的 token 优化分析。

Repomix MCP Server 是什么

Repomix 是一个将整个仓库打包为单个 AI 友好文件的工具（参见项目根目录 README.md）。而 Repomix MCP Server 则是将这一能力以 Model Context Protocol（MCP）标准暴露出来的服务：它把本地或远程代码库打包成结构化的 AI 友好格式，让 AI 助手在不做任何手动文件准备的前提下直接分析代码，同时优化 token 使用并提供一致的输出结构。

从源码看，MCP 服务器的入口非常轻量：CLI 的 --mcp 参数会进入 mcpAction.ts，随后调用 mcpServer.ts 中的 runMcpServer，通过 StdioServerTransport 以标准输入输出（stdio）与客户端通信（见 mcpServer.ts）。服务器在启动时注册一系列工具，并向客户端注入一段说明指令，描述自身能力边界与正确用法（见 mcpServer.ts）。

安装前提

在安装之前，你需要满足以下两个条件：

1. Node.js 22.0.0 或更高版本
2. npm（Node Package Manager）

两者缺一不可，因为下文推荐的配置方式正是借助 npx 直接拉取并运行 Repomix 包，无需全局安装。

安装与配置 MCP Server

配置文件位置

Repomix MCP Server 的配置需要写入你所用 LLM 客户端的 MCP 设置文件中。官方文档给出了四类常见客户端的配置路径：

客户端	配置文件路径
Cline（VS Code 扩展）	~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
Roo Code（VS Code 扩展）	~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json
Cursor	[项目根目录]/.cursor/mcp.json

上述路径以 macOS 为示例（~/Library/...）；Windows 与 Linux 上对应的是各自的用户配置目录，格式与内容完全相同。文档同时提醒：即使是在 Windows 上，配置文件中的路径分隔符也应统一使用正斜杠 /。

通用配置示例

将以下配置加入所选客户端的设置文件：

{
  "mcpServers": {
    "repomix": {
      "command": "npx",
      "args": [
        "-y",
        "repomix",
        "--mcp"
      ],
      "disabled": false,
      "autoApprove": []
    }
  }
}

这段配置利用 npx 直接运行 Repomix，无需全局安装：-y 表示自动确认下载，repomix 指定要执行的包，--mcp 则让 Repomix 以 MCP 服务器模式启动。disabled 控制该服务器是否启用，autoApprove 可配置允许自动授权的工具（默认留空，即每个工具调用都需要确认）。

其他客户端与替代运行方式

除上述 JSON 配置外，README 还补充了多种接入方式（见 README.md 中 "Configuring MCP Servers" 一节）：

• VS Code：可直接使用安装徽章一键添加，或在命令行执行：

  code --add-mcp '{"name":"repomix","command":"npx","args":["-y","repomix","--mcp"]}'
  

• Claude Code：使用其内置的 MCP 管理命令：

  claude mcp add repomix -- npx -y repomix --mcp
  

• Docker 替代 npx：若你倾向容器化运行，可将命令替换为 Docker：

  {
    "mcpServers": {
      "repomix-docker": {
        "command": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "ghcr.io/yamadashy/repomix",
          "--mcp"
        ]
      }
    }
  }
  

配置完成后，AI 助手便可以直接调用 Repomix 的能力来分析代码库，无需手动准备文件。

可用的 MCP 工具

配置完成后，你将获得以下 Repomix 工具。其中五个核心工具在官方安装文档中有详细说明，另外两个文件系统工具仅在沙箱模式下提供（见下文"沙箱模式"一节）。

1. pack_codebase：打包本地代码目录

该工具将本地代码目录打包为合并后的 XML 文件供 AI 分析。它会分析代码库结构、提取相关代码内容，并生成包含指标统计、文件树和格式化代码内容的综合报告。

参数：

参数	必填	默认值	说明
directory	是	—	待打包目录的绝对路径
compress	否	false	启用 Tree-sitter 压缩，提取关键代码签名与结构、移除实现细节，可减少约 70% token 且保留语义。由于 grep_repomix_output 支持增量内容检索，一般无需开启；仅当大仓库确实需要完整代码内容时使用
includePatterns	否	—	用 fast-glob 模式指定要包含的文件，多个模式用逗号分隔（如 "**/*.{js,ts}"、"src/**,docs/**"），仅匹配的文件会被处理
ignorePatterns	否	—	用 fast-glob 模式指定额外排除的文件，多个模式用逗号分隔（如 "test/**,*.spec.js"、"node_modules/**,dist/**"）。这些模式是对 .gitignore 与内置排除规则的补充
topFilesLength	否	10	在指标摘要中按大小展示的最大文件数量

示例调用：

{
  "directory": "/path/to/your/project",
  "compress": false,
  "includePatterns": "src/**/*.ts,**/*.md",
  "ignorePatterns": "**/*.log,tmp/",
  "topFilesLength": 10
}

源码佐证：在 packCodebaseTool.ts 中，该工具的参数由 zod schema 定义，compress 默认 false、topFilesLength 默认 10（见 packCodebaseTool.ts）。非沙箱模式下 directory 被描述为"任意该进程可读的目录均可打包"；沙箱模式下则必须是相对工作区根目录的路径（见 packCodebaseTool.ts）。工具内部会创建临时工作区，将参数映射为 runCli 的 CLI 选项后调用核心打包流水线，最后返回 outputId、outputFilePath、totalFiles、totalTokens 等结构化结果。此外，实际工具还额外支持 style（xml/markdown/json/plain，默认 xml）与 outputPatterns（按文件粒度控制包含级别，首个匹配生效，directoryStructureOnly 优先于 compress）两个进阶参数，对应配置文件中的 output.patterns 选项。

2. 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/branch"）
compress	否	false	同 pack_codebase，启用 Tree-sitter 压缩（约减少 70% token）
includePatterns	否	—	fast-glob 包含模式，逗号分隔
ignorePatterns	否	—	fast-glob 排除模式，逗号分隔，补充 .gitignore 与内置排除
topFilesLength	否	10	指标摘要中展示的最大文件数量

示例调用：

{
  "remote": "yamadashy/repomix",
  "compress": false,
  "includePatterns": "src/**/*.ts,**/*.md",
  "ignorePatterns": "**/*.log,tmp/",
  "topFilesLength": 10
}

源码佐证：该工具同样基于 zod schema 校验参数（见 packRemoteRepositoryTool.ts）。实现上它将 remote 等参数透传给 CLI 的 --remote 流程，并默认开启安全扫描（securityCheck: true），自动排除匹配已知凭据格式的文件。值得注意的是，回显给模型的仓库描述会经 redactUrl 脱敏处理——带凭据的远端地址不会残留在 MCP 对话记录、客户端日志和模型上下文中（见 packRemoteRepositoryTool.ts）。从安全模型看，远端仓库的 repomix.config.* 默认不会加载，只有显式使用 --remote-trust-config 才会在交互式终端中展示并确认后加载（参见 README.md 中 "Remote Repository Config Trust" 一节）。

3. attach_packed_output：附加既有打包产物

该工具将已有的 Repomix 打包输出文件附加给 AI 分析，让你无需重新处理即可使用之前生成的打包仓库。

参数：

参数	必填	默认值	说明
path	是	—	包含 repomix-output.xml 的目录路径，或打包仓库 XML 文件的直接路径
topFilesLength	否	10	指标摘要中展示的最大文件数量

特性：

• 既接受包含 repomix-output.xml 的目录，也接受 XML 文件的直接路径
• 将文件注册到 MCP 服务器，并返回与 pack_codebase 相同的结构
• 无需重新处理即可访问既有打包产物
• 适合与之前生成的打包仓库配合使用

示例调用：

{
  "path": "/path/to/directory/with/repomix-output.xml",
  "topFilesLength": 10
}

4. read_repomix_output：读取打包输出文件

该工具读取 Repomix 生成的输出文件内容，支持通过行号范围对大文件进行部分读取，专为文件系统访问受限的环境（如 Web 环境、沙箱应用）设计。

参数：

参数	必填	说明
outputId	是	要读取的 Repomix 输出文件的 ID
startLine	否	起始行号（从 1 开始，含该行）。不指定则从开头读取
endLine	否	结束行号（从 1 开始，含该行）。不指定则读到末尾

特性：

• 专门为 Web 环境或沙箱应用设计
• 通过 ID 检索先前生成的输出内容
• 无需文件系统访问即可读取打包代码库
• 支持大文件的部分读取

示例调用：

{
  "outputId": "8f7d3b1e2a9c6054",
  "startLine": 100,
  "endLine": 200
}

源码佐证：outputId 背后的机制是内存中的输出文件注册表——打包工具在生成输出时将文件路径与 ID 关联（见 mcpToolRuntime.ts），read_repomix_output 通过 ID 反查路径再读取内容。实现中还包含严格的参数校验：起始行必须 ≥ 1、结束行必须 ≥ 1、起始行不得大于结束行、起始行不得超出文件总行数（见 readRepomixOutputTool.ts）。

5. grep_repomix_output：在打包输出中检索

该工具使用类似 grep 的功能在 Repomix 输出文件中搜索模式，支持 JavaScript RegExp 正则语法，并返回匹配行及可选上下文行。

参数：

参数	必填	默认值	说明
outputId	是	—	要搜索的 Repomix 输出文件 ID
pattern	是	—	搜索模式（JavaScript RegExp 正则语法）
contextLines	否	0	每个匹配项前后显示的上下文行数。若指定了 beforeLines/afterLines 则被覆盖
beforeLines	否	—	每个匹配项前显示的上下文行数（类似 grep -B），优先级高于 contextLines
afterLines	否	—	每个匹配项后显示的上下文行数（类似 grep -A），优先级高于 contextLines
ignoreCase	否	false	是否忽略大小写进行匹配

特性：

• 使用 JavaScript RegExp 语法实现强大的模式匹配
• 支持上下文行，便于理解匹配内容
• 可分别控制前后上下文行数
• 支持区分大小写与不区分大小写的搜索

示例调用：

{
  "outputId": "8f7d3b1e2a9c6054",
  "pattern": "function\\s+\\w+\\(",
  "contextLines": 3,
  "ignoreCase": false
}

源码佐证：该工具的搜索实现将内容按行拆分后逐行匹配正则，输出包含 lineNumber、line、matchedText 的匹配数组，并按 -B/-A 语义格式化带上下文的结果（见 grepRepomixOutputTool.ts）。无效的正则会被捕获并返回明确的错误信息。由于打包输出往往有数 MB 级别，实现特意避免重复拆分内容以控制性能（见 grepRepomixOutputTool.ts）。

沙箱模式与文件系统工具

默认情况下，MCP 服务器可以读取宿主用户可读的任何路径。这对受信任的本地助手很方便，但当服务器暴露给不受信任的客户端或 Agent 时则过于宽泛。--sandbox 标志可将服务器的文件工具限定在单个工作区目录内：

# 限定在当前工作目录
repomix --mcp --sandbox

# 限定到指定目录
repomix --mcp --sandbox path/to/project

沙箱模式下所有路径都相对于工作区根目录（绝对路径、~、..、Windows 盘符/UNC 路径以及通过符号链接逃逸出根目录的路径都会被拒绝），并且只注册只读、受限的工具；远端打包、技能生成、附加外部输出均被禁用。此时会额外注册两个文件系统工具（见 mcpServer.ts）：

• file_system_read_file：读取沙箱工作区内的文件，路径相对于工作区根目录（如 src/index.ts）
• file_system_read_directory：列出沙箱工作区内的目录内容，带 [FILE] / [DIR] 标识

需要强调的是，这是工具面（tool surface）层面的应用级隔离，并非操作系统级沙箱；且沙箱工具注册表与错误处理做了针对性设计——错误信息只回传基于错误码的固定原因（如 not found、permission denied），绝不转发可能泄露宿主路径的原始 error.message（见 mcpToolRuntime.ts）。另外，沙箱模式下打包调用会跳过本地与全局配置文件、禁用基于 git 的排序，以避免不可信工作区通过配置或 .git/config 执行宿主命令（见 packCodebaseTool.ts）。

验证安装

配置完成后按以下步骤验证是否工作正常：

1. 重启你的 LLM 应用（Cline、Claude Desktop 等）
2. 运行一条简单命令测试连接，例如：

   请使用 Repomix 将本地目录 /path/to/project 打包，用于 AI 分析。
   

   或：

   请使用 Repomix 获取并打包 GitHub 仓库 yamadashy/repomix 用于 AI 分析。
   

若助手能够返回包含指标、目录结构与文件内容的打包报告，说明接入成功。

使用示例

以下是 Repomix MCP Server 与 AI 助手配合的典型场景：

本地代码库分析

你能分析一下我位于 /path/to/project 的项目代码吗？请先用 Repomix 打包它。

远端仓库分析

我想让你审查 GitHub 仓库 username/repo 的代码。请先用 Repomix 打包它。

指定文件类型分析

请打包我位于 /path/to/project 的项目，但只包含 TypeScript 文件和 Markdown 文档。

这类自然语言指令背后，助手会依次调用 pack_codebase/pack_remote_repository 生成打包产物，再通过 read_repomix_output 与 grep_repomix_output 进行增量、定向的内容读取，从而在控制上下文消耗的前提下完成深入分析。

故障排查

常见问题与解决方案

1. MCP 服务器连接问题

   • 检查 MCP 设置文件的 JSON 语法是否正确
   • 确保网络连接正常（npx 需要联网拉取包）
   • 检查是否有其他 MCP 服务器造成冲突

2. 打包失败

   • 确认指定的目录或仓库确实存在
   • 检查是否有足够的磁盘空间
   • 处理远端仓库时确保网络连通
   • 先用简单的参数尝试，再逐步增加复杂度

3. 配置中的 JSON 解析错误

   • 确保 MCP 设置文件格式正确
   • 确认所有路径都使用正斜杠，即使在 Windows 上也是如此
   • 检查配置中是否有缺失的逗号或括号

安全要点小结

• 凭据扫描：所有打包流程默认启用基于 Secretlint 的安全检查，匹配已知凭据格式的文件会被标记或排除；通过 attach_packed_output 附加的不可信文件在每次提供内容前都会重新扫描（见 readRepomixOutputTool.ts 与 grepRepomixOutputTool.ts）。
• 远端配置信任：远端仓库的 repomix.config.* 默认不加载，防止不可信仓库通过配置文件执行代码；只有显式使用 --remote-trust-config（或 REPOMIX_REMOTE_TRUST_CONFIG=true）且经交互确认后才加载（参见 README.md 中 "Remote Repository Config Trust" 一节）。
• 沙箱边界：面向不可信客户端时务必使用 --sandbox，将文件访问限定在工作区根目录，并避免在日志与回显中泄露宿主路径。

更多细节可继续查阅仓库根目录的 README.md 与本安装指南 llms-install.md，以及 MCP 服务器源码目录 src/mcp 下的工具实现与测试用例，以便深入理解各参数的底层行为。