使用 Semble MCP 優化 Claude Code 的程式碼搜尋 — 減少98% Token 的機制與實踐指南

使用 Semble MCP 優化 Claude Code 的程式碼搜尋 — 減少98% Token 的機制與實踐指南

什麼是 Semble MCP？

Semble MCP 是專為 AI 程式設計代理設計的高速本地程式碼搜尋伺服器。目的是為 Claude Code、Cursor、OpenAI Codex 等代理提供「比 grep 更智慧、比 RAG 更輕量的程式碼探索」。

通常 AI 代理在查找程式碼時會組合使用 grep、ripgrep、全檔案讀取和 embeddings 搜尋，而 Semble 對此進行了專項優化。

「認證處理在哪裡？」
「save model 的實作」
「Firebase 初始化」

透過這樣的自然語言搜尋，快速返回所需的程式碼片段。

主要特性

超高速本地處理

Semble 僅使用 CPU 執行。無需 GPU。

• 儲存庫索引產生：約 250ms
• 搜尋：約 1.5ms

大幅減少 Token 使用量

與「grep + 檔案讀取」相比，存取所需程式碼所用的 Token 減少約98%。在大型專案上長時間執行 Claude Code 時，降低成本的效果非常顯著。

安全性：完全本地化設計

官方說明強調：

• 無需 API 金鑰
• 不與外部服務通訊
• 完全透過本地路徑執行

索引產生、搜尋、embeddings 產生和 BM25 搜尋全部在本地 PC 內處理。

如何新增至 Claude Code

需要 uv。可以用以下指令新增：

claude mcp add semble -s user -- uvx --from "semble[mcp]" semble

安裝時從 PyPI 取得套件，但此後的執行完全在本地進行。

與 Sub-agent 的結合

Semble 除了 MCP 版本外還有 CLI 版本。由於 Claude Code 的 Sub-agent 在某些情況下可能無法使用 MCP，建議在 CLAUDE.md 或 AGENTS.md 中明確記載 CLI 版本的使用。

Use `semble search` instead of grep for codebase exploration.

這樣撰寫後，多個代理將統一使用 Semble。

實際使用方式

# 自然語言搜尋
semble search "認證流程" ./my-project
semble search "Firebase 初始化" ./my-project
semble search "查詢提交處理" ./my-project --top-k 10

# 相關程式碼探索（指定檔案路徑和行號）
semble find-related src/auth.py 42 ./my-project

與其他工具的職責劃分

Semble 僅是專注於程式碼搜尋的工具。了解與其他 MCP 的職責劃分非常重要。

具體而言：

• context7 → 「想了解 Jetpack Compose 的官方規格」
• Semble → 「想在自己的專案中查找 Compose 程式碼」

建置、lint、測試執行和資料庫操作不在 Semble 的範圍內。

適合哪些專案？

效果最好的情況

• 大型儲存庫
• Android 專案（Jetpack Compose、Firebase 混合、multi-module 結構）
• 透過 AGENTS.md 大量使用 Sub-agent
• 長期持續使用 Claude Code

不太需要的情況

• 小型儲存庫（幾個檔案）
• 一次性任務

安全注意事項

雖然 Semble 本身是完全本地化設計，但使用時有幾點需要注意。

搜尋結果會傳遞給 LLM

Semble 不會向外部傳送程式碼，但它返回的搜尋結果會透過 Claude Code 傳遞給 LLM。

本地程式碼
  ↓ Semble 搜尋（完全本地）
  ↓ 將搜尋結果傳遞給 Claude
  ↓ LLM 處理

也就是說，需要考慮的是傳遞給 LLM，而非 Semble 本身。

安全設定範例

如果安全是優先考量，建議使用最小化外部通訊 MCP 的設定。

Claude Code
├ Semble (local)
├ filesystem MCP (local)
├ git MCP (local)
└ terminal (local)

處理機密程式碼或業務資料時，確認 LLM 側的 telemetry 和對話保留政策比 Semble 本身更重要。

總結

Semble MCP 是專業使用 Claude Code 的工程師的高價值工具。

• 大幅降低 Token 成本（最高98%）
• 自然語言程式碼搜尋
• 完全本地化設計，安全可靠
• 與 Sub-agent 結合效果加倍

只需將原來用 grep 掃描大量檔案的部分替換為 Semble，代理的執行效率就會大幅提升。特別是在大型專案和多代理設定中，值得考慮盡早引入。