第三方工具更新 2026.11.16

Serena MCP 教學:Windows 安裝、Codex 與 Claude Code 設定

Windows 安裝 Serena MCP,接 Codex 與 Claude Code。用符號與引用定位計算問題,只替換目標函式,再以五項 Python 斷言驗證修改。

Serena 把「找函式、看定義、找引用」接給 AI 寫程式工具。常請 AI 修改既有專案、需要先查清楚呼叫關係時,很適合用它定位問題;只寫幾十行小腳本,內建搜尋通常就夠了。

下面在 Windows 用一個銷售計算案例,帶你接上 Codex,找出負數金額被算進總額的原因,以及會受修改影響的函式。接著只替換目標函式,再用五個案例核對結果。

安裝:用獨立 Python 環境避免找錯執行檔

需要已安裝的 uv、Codex CLI 或 Claude Code。開一個空的專案資料夾,在 PowerShell 執行:

uv venv --python 3.12 .venv
uv pip install --python .venv\Scripts\python.exe serena-agent==2.1.0 jedi-language-server==0.47.0
$serena = (Resolve-Path .venv\Scripts\serena.exe).Path
$project = (Get-Location).Path
$env:PATH = "$project\.venv\Scripts;$env:PATH"
& $serena start-mcp-server --help

最後一行會列出 --project、--context 與 --agent-interface 等選項。Serena 與 Jedi 必須用同一個環境;上面的 PATH 設定讓 Serena 能找到 jedi-language-server,下面註冊時也會將它明確傳給 MCP。

建立 .serena/project.yml,指定這個 Python 案例使用 Jedi:

project_name: sales-project
language_servers: [python_jedi]

再建立 sales.py:

def total_sales(amounts):
    return sum(amounts)

def report():
    return total_sales([120, 80])

這個案例的需求是「負數調整不計入總額」,但目前 total_sales([120, 80, -10]) 會得到 190。接下來請 AI 找原因與呼叫者,先保持檔案原樣。

接上 Codex CLI

在同一個 PowerShell 視窗執行:

codex mcp add serena --env "PATH=$env:PATH" -- $serena start-mcp-server --context codex --project $project --agent-interface tools --enable-web-dashboard false --enable-gui-log-window false
codex mcp list

清單應出現 serena 與剛才的啟動命令。重新開啟專案的 Codex 對話,貼上下一節的提示詞。觀察工具呼叫:應出現 Serena 的 get_symbols_overview 或 find_symbol,才表示這次分析確實用到它。

--agent-interface tools 固定使用本文的個別工具介面。Serena 2 也有 REPL 介面,工具名稱與操作方式不同;照本文練習時先保留這個參數。

接上 Claude Code

在專案資料夾執行:

claude mcp add serena --scope project --transport stdio --env "PATH=$env:PATH" -- $serena start-mcp-server --context claude-code --project $project --agent-interface tools --enable-web-dashboard false --enable-gui-log-window false
claude mcp list

健康檢查會列出 serena;這次看到的狀態是 ✓ Connected。--scope project 把設定放在專案 .mcp.json,方便核對綁定的路徑。

使用 Cursor 時,請參考 Serena 官方客戶端設定,選用 ide context。

三個可以直接貼上的用途

1. 先看這個檔案有哪些函式

用 Serena 讀取 initial_instructions,再對 sales.py 執行 get_symbols_overview。
列出函式名稱,接著用 find_symbol 只讀 total_sales 的定義。先不要修改或執行命令。

這份檔案會列出 total_sales、report;指定定義的內容是 return sum(amounts)。在大檔案中,可以先用這個方式縮小要讀的範圍。

2. 修改前先知道誰會受影響

用 Serena 的 find_referencing_symbols,找 sales.py 裡 total_sales 的引用。
指出呼叫者名稱與呼叫內容,說明如果改變 total_sales 的輸入介面,哪裡需要一起檢查。不要修改。

這裡會找到 report,它呼叫 total_sales([120, 80])。如果只調整加總規則,這個正數案例可作為回歸檢查;若改參數型態,就要一起檢查呼叫端。

3. 修改目標函式並驗證

用 Serena 查 sales.py 的 total_sales 定義與引用。需求是忽略負數調整。
用 replace_symbol_body 只替換 total_sales,再用 find_symbol 讀回結果,保留 report 原樣。
允許在這個專案執行 Python,核對混合金額、全正數、空清單、全負數與 report。

這次 replace_symbol_body 回傳 OK,讀回的函式是:

def total_sales(amounts):
    return sum(amount for amount in amounts if amount >= 0)

再於專案終端執行:

.venv\Scripts\python.exe -c "from sales import total_sales, report; assert total_sales([120,80,-10])==200; assert total_sales([120,80])==200; assert total_sales([])==0; assert total_sales([-10])==0; assert report()==200; print('PASS: all 5 assertions')"

五項都通過,混合金額從 190 改為 200,正數呼叫端仍得到 200。這個規則來自案例需求;真實帳務是否該忽略負數,必須先與業務規則確認。

Serena 的符號位置採從 0 起算的行號;對照編輯器顯示行號時要留意這一點。

常見錯誤與解法

終端能用,MCP 卻找不到 serena

檢查註冊命令的執行檔是否是 .venv\Scripts\serena.exe 的完整路徑。啟動客戶端的環境可能沒有終端裡的 PATH;明確指定路徑,比依賴另一個 Python 環境可靠。

連上了,卻找不到函式

先核對 --project 指向包含 sales.py 的資料夾,以及 .serena/project.yml 是否指定 python_jedi。若看到 LanguageServerTerminatedException,確認 Jedi 已裝進同一個 venv,且註冊命令的 --env 有傳入包含該 venv Scripts 的 PATH;這次獨立重跑確實因漏掉 PATH 而失敗。若換成其他語言,先查官方的語言伺服器需求。

看不到 get_symbols_overview

核對啟動參數是否包含 --agent-interface tools,改完後重連 MCP。Serena 2 的 REPL 介面不會把每個操作都列成獨立工具;介面不同,不能只看名稱判斷連線壞了。

顯示「MCP tool call requires approval, but approval policy is never」

早先的唯讀工作階段曾出現這個訊息,當時程式沒有改動。它表示客戶端拒絕該次操作;先檢查專案允許的編輯與命令權限,再開新對話。這次一次性專案在允許操作的工作階段完成替換與測試;不需要靠重裝 Serena 解決權限問題。

限制、費用與何時換工具

引用搜尋取決於語言伺服器能理解的程式結構;動態匯入、字串拼出的名稱仍需要文字搜尋與測試補強。本文的小檔案不能用來估計大型專案的索引時間或節省多少 token。

Serena 本機開源版本不另收模型 API 費,AI 客戶端與模型用量分開計算;JetBrains 外掛後端另有費用。Serena 應用程式採 GPL-3.0-or-later,SolidLSP 元件採 MIT。啟動時的使用資訊回報可用環境變數 SERENA_USAGE_REPORTING=false 關閉。

找 TODO 或固定字串,用原有搜尋通常更快;需要把整個專案打包給另一個對話時,可看 Repomix。要核對某個函式的呼叫關係,才是 Serena 在這個案例的用武之地。

FAQ

Serena MCP 有什麼用途?

它讓 AI 用符號名稱取得定義、追蹤引用並進行程式操作。實際上可以先問「哪個函式造成這個結果、誰會受影響」,再決定修改範圍。它提供程式結構資訊,需求判斷仍要靠開發者與測試。

Serena 可以接 Codex 和 Claude Code 嗎?

可以,兩者分別使用 codex 與 claude-code context。本文提供 Windows 註冊命令,以及 Codex 的定位、替換與測試流程。切換專案時,記得核對啟動命令裡的 --project 路徑。

已經有 grep,為什麼還要裝 Serena?

文字搜尋適合找字串;Serena 的引用查詢會回傳呼叫所在的符號,例如這裡的 report。當你需要依照函式結構追查影響範圍時,這個差異才有價值。小腳本或單純找字串,先用現有搜尋即可。

為什麼 Serena 連線成功,AI 還是直接讀整個檔案?

連線成功只表示工具可用,模型仍會選擇自己的讀檔工具。先明確指定 get_symbols_overview、檔名和要讀的符號,並檢查實際呼叫。官方也提供 hooks 的進階設定,可在基本流程確認正常後再評估。

官方參考

我們測了什麼

2026-11-16,Windows、Python 3.12、Serena 2.1.0、Jedi language server 0.47.0、Codex CLI 0.169.0。 Codex 實際呼叫符號概覽、定義與引用工具,定位銷售計算問題;Claude Code 執行 add/list 並顯示 Connected。 新增修改測試使用 replace_symbol_body、讀回函式,再以 Python 通過混合金額、正數、空清單、全負數及 report 五項斷言。Cursor、大型專案及其他語言未測。

訂閱 AI 工具精選與使用建議

有值得推薦的新工具、實測發現或重要更新時,寄到你的信箱。

訂閱後先寄給你一份每月更新的 AI 工具與 Skill 清單。有值得推薦的工具、實測發現或重要更新時才寄信,隨時可以退訂。隱私權說明

快完成了,請到信箱收確認信點信裡的按鈕確認訂閱,就會收到工具清單的下載連結。沒看到的話,看一下垃圾郵件或「促銷內容」分頁。

也可以在這些平台追蹤: