MCP伺服器

Repomix 支援 Model Context Protocol (MCP)，允許 AI 助手直接與您的程式碼庫交互。當作為 MCP 伺服器運行時，Repomix 提供了工具，使 AI 助手能夠在無需手動準備文件的情況下打包本地或遠端倉庫進行分析。

NOTE

這是一個實驗性功能，我們將根據用戶反饋和實際使用情況積極改進

將 Repomix 作為 MCP 伺服器運行

要將 Repomix 作為 MCP 伺服器運行，請使用 --mcp 標誌：

repomix --mcp

這會以 MCP 伺服器模式啟動 Repomix，使其可供支援 Model Context Protocol 的 AI 助手使用。

沙箱模式

依預設，MCP 伺服器可以讀取主機使用者所能存取的任何路徑。這對受信任的本地助手而言很方便，但當伺服器暴露給不受信任的用戶端或 agent 時，範圍就顯得過於寬鬆。--sandbox 旗標會將伺服器的文件工具限制在單一工作區目錄內：

# 限制在目前工作目錄
repomix --mcp --sandbox

# 限制在特定目錄
repomix --mcp --sandbox path/to/project

當沙箱模式啟用時：

• 每個路徑都相對於工作區根目錄解析。 絕對路徑、~、.. 以及 Windows 磁碟機／UNC 路徑都會被拒絕，解析後落在根目錄之外的路徑（包括透過符號連結的情況）也會被捨棄。傳回結果與錯誤訊息同樣採用相對路徑，因此不會暴露主機路徑。這適用於下方工具參考中的 directory 與 path 參數：在沙箱模式下，請傳入相對於工作區根目錄的路徑，而非這些表格中原本描述的絕對路徑。
• 僅會註冊唯讀且限定在根目錄內的工具： pack_codebase、read_repomix_output、grep_repomix_output、file_system_read_file 和 file_system_read_directory。遠端打包、Skills 生成以及附加外部輸出等功能皆會被停用，因為它們會存取網路、寫入文件或參照任意路徑。這兩個 file_system_* 工具本身也僅在沙箱模式下才可用，其可存取範圍由工作區根目錄所限定。

這是在應用程式層級對工具介面所做的限制（縱深防禦），並非作業系統層級的沙箱。若要為不受信任的用戶端託管此伺服器，仍應在您所在平台慣用的隔離機制下運行（容器、專用使用者等）。

--sandbox 僅影響 MCP 伺服器；若未搭配 --mcp 使用則不會生效。

配置 MCP 伺服器

要將 Repomix 作為 MCP 伺服器與 Claude 等 AI 助手一起使用，您需要配置 MCP 設置：

對於 VS Code

您可以使用以下方法之一在 VS Code 中安裝 Repomix MCP 伺服器：

1. 使用安裝徽章：

2. 使用命令行：

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"]}'

對於 Cline（VS Code 擴展）

編輯 cline_mcp_settings.json 文件：

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

對於 Cursor

在 Cursor 中，從 Cursor Settings > MCP > + Add new global MCP server 添加一個新的 MCP 伺服器，配置與 Cline 類似。

對於 Claude Desktop

使用與 Cline 類似的配置編輯 claude_desktop_config.json 文件。

對於 Claude Code

要在 Claude Code 中配置 Repomix 作為 MCP 伺服器，請使用以下命令：

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

或者，您可以使用官方Repomix外掛獲得更便捷的體驗。外掛提供自然語言指令和更簡單的設定。詳情請參閱Claude Code外掛文件。

使用 Docker 代替 npx

您可以使用 Docker 代替 npx 來運行 Repomix 作為 MCP 伺服器：

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

可用的 MCP 工具

當作為 MCP 伺服器運行時，Repomix 提供以下工具：

pack_codebase

此工具將本地程式碼目錄打包成一個用於 AI 分析的 XML 文件。它分析程式碼庫結構，提取相關程式碼內容，並生成包含指標、文件樹和格式化程式碼內容的綜合報告。

參數：

參數	必需	預設值	說明
directory	是	—	要打包的目錄的絕對路徑
compress	否	false	啟用 Tree-sitter 壓縮以提取基本程式碼簽名和結構，同時刪除實現細節。在保持語義含義的同時減少約 70% 的令牌使用量。由於 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.patterns。
topFilesLength	否	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_remote_repository

此工具獲取、克隆並將 GitHub 倉庫打包成一個用於 AI 分析的 XML 文件。它自動克隆遠端倉庫，分析其結構，並生成綜合報告。

參數：

參數	必需	預設值	說明
remote	是	—	GitHub 儲存庫 URL 或 user/repo 格式（例如 "yamadashy/repomix"、"https://github.com/user/repo" 或 "https://github.com/user/repo/tree/branch"）
compress	否	false	啟用 Tree-sitter 壓縮以提取基本程式碼簽名和結構，同時刪除實現細節。在保持語義含義的同時減少約 70% 的令牌使用量。由於 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 時豁免特定檔案）。
topFilesLength	否	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
}

read_repomix_output

此工具讀取 Repomix 生成的輸出文件的內容。支援對大文件進行行範圍指定的部分讀取。此工具專為直接文件系統存取受限的環境而設計。

參數：

參數	必需	預設值	說明
outputId	是	—	要讀取的 Repomix 輸出檔案的 ID
startLine	否	檔案開頭	起始行號（從 1 開始，包含）
endLine	否	檔案末尾	結束行號（從 1 開始，包含）

功能：

• 專為基於 Web 的環境或沙箱應用程式設計
• 使用其 ID 檢索先前生成的輸出內容
• 無需文件系統存取權限即可存取打包的程式碼庫
• 支援大文件的部分讀取

示例：

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

grep_repomix_output

此工具使用 JavaScript RegExp 語法的類似 grep 的功能在 Repomix 輸出文件中搜尋模式。返回匹配行及其周圍的可選上下文行。

參數：

參數	必需	預設值	說明
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
}

file_system_read_file 和 file_system_read_directory

這兩個文件系統工具僅在沙箱模式（--sandbox）下才可用，其可存取範圍由工作區根目錄所限定。若不使用 --sandbox，它們不會被註冊。

1. file_system_read_file

• 讀取相對於工作區根目錄之路徑下的文件內容（例如 src/index.ts）
• 作為額外的啟發式防護措施，拒絕符合已知敏感資訊格式（Secretlint）的內容；存取邊界是工作區根目錄，而非該掃描
• 對無效路徑返回清晰的錯誤訊息，且不會暴露主機路徑

2. 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 伺服器使用的好處

將 Repomix 作為 MCP 伺服器使用提供了幾個優勢：

1. 直接整合：AI 助手可以直接分析您的程式碼庫，無需手動文件準備。
2. 高效工作流程：通過消除手動生成和上傳文件的需求，簡化了程式碼分析過程。
3. 一致輸出：確保 AI 助手以一致、最佳化的格式接收程式碼庫。
4. 進階功能：利用 Repomix 的所有功能，如程式碼壓縮、令牌計數和安全檢查。

配置完成後，您的 AI 助手可以直接使用 Repomix 的功能來分析程式碼庫，使程式碼分析工作流程更加高效。

相關資源

• Claude Code 外掛 - 便捷的 Claude Code 外掛整合
• 設定 - 自訂 Repomix 行為
• 命令列選項 - 完整的 CLI 參考
• 輸出格式 - 了解可用的輸出格式