MCP Inspector 怎麼用：安裝、啟動命令、調試 MCP 伺服器與 v2 的變化

本文根據 MCP 官方文檔《MCP Inspector》、Inspector 倉庫 README 和《v1 → v2 migration》整理，資料核對於 2026-10-11。沒有在本機運行，介面細節以官方文檔為準。

適用於誰

• 搜「mcp inspector 使用」「mcp inspector 怎麼用」「mcp inspector 安裝」「mcp inspector 是什麼」的人；
• 自己寫了 MCP 伺服器，想在接進 Claude 或 Cursor 之前先單獨測一下的人；
• 別人的 MCP 伺服器在客戶端裏連不上，想弄清是伺服器的問題還是配置的問題的人；
• 照着舊教學敲命令，發現端口和參數對不上的人。

結論先說

1. MCP Inspector 是 MCP 官方的調試工具，用來測試和調試 MCP 伺服器：連上去，看它提供了哪些工具、資源和提示，手動調用並查看往來的消息。
2. 不用安裝，一條 npx @modelcontextprotocol/inspector 就能運行。要求 Node 22.19.0 或更高。
3. 一個包、三種介面：預設是瀏覽器裏的網頁介面；加 --cli 是可以寫進腳本的命令行；加 --tui 是終端裏的交互介面。
4. 啟動後打印的地址裏帶着一次性的訪問令牌，要用那個完整地址打開。
5. 現在是 v2。舊教學裏的代理端口 6277 已經沒有了，令牌的環境變量也改了名。

一、三種模式

官方說明三者基於同一套內核：同樣的傳輸方式、同樣的配置文件、同樣的 OAuth 狀態，連接行為一致。

模式參數必須放在命令的最前面，並且最多隻能有一個。

二、網頁模式：連一個本地伺服器

把啟動伺服器的命令原樣跟在 Inspector 後面：

bash
# 啟動網頁介面，連接一個本地的 stdio 伺服器
npx @modelcontextprotocol/inspector node path/to/server/index.js

# 或者不帶目標啟動，在介面裏添加伺服器
npx @modelcontextprotocol/inspector

命令會打印一個帶有本次啟動專用令牌的地址，並自動在瀏覽器裏打開。不想自動打開時，設定環境變量 MCP_AUTO_OPEN_ENABLED=false。

連接已發佈的伺服器，同樣是把它的啟動命令跟在後面。官方的 npm 包示例：

bash
npx -y @modelcontextprotocol/inspector npx @modelcontextprotocol/server-filesystem ~/Desktop

Python 包發佈的伺服器也是一樣的做法，把它的啟動命令（例如通過 uv 的工具運行器啟動）接在後面即可。官方提醒：每個伺服器需要的命令和參數都不同，先讀它自己的 README。

連接遠程伺服器，用 --server-url：

bash
npx @modelcontextprotocol/inspector --server-url https://api.example.com/mcp --transport http

遷移文檔補充：不寫 --transport 時，網址必須以 /mcp 或 /sse 結尾，工具才能判斷傳輸方式；否則要顯式寫 --transport http 或 --transport sse。

給 stdio 伺服器傳環境變量，用 -e：

bash
npx @modelcontextprotocol/inspector -e KEY=value -- node build/index.js

三、在網頁介面裏做什麼

連接成功後，典型的檢查順序：

1. 看工具列表：名稱、說明和參數定義是不是你期望的。模型只看得到這些，說明寫得含糊，模型就用不對；
2. 手動調用工具：填參數，執行，看返回的結果和報錯；
3. 看資源和提示：伺服器有提供的話，逐個讀取確認；
4. 看消息往來：介面裏可以查看 JSON-RPC 的請求和響應，定位是請求格式不對還是伺服器處理出錯。

官方文檔有一頁專門逐個標籤頁介紹網頁介面，介面隨版本變化，細節以那一頁為準。

四、命令行模式

適合寫進腳本或 CI。官方示例：

bash
# 列出伺服器的工具然後退出
npx @modelcontextprotocol/inspector --cli node path/to/server/index.js --method tools/list

# 調用一個工具，把結果交給 jq
npx @modelcontextprotocol/inspector --cli https://api.example.com/mcp --transport http \
  --method tools/call --tool-name get_weather --tool-arg city=Boston --format json | jq .result

兩條容易出錯的規則（來自遷移文檔）：

• --cli 模式下，目標必須寫在所有參數之前，否則會被悄悄丟掉；
• 退出碼從 v1 的 0 / 1 變成了 0 到 5，工具調用失敗（結果裏 isError: true）現在以 5 退出。以前失敗後仍繼續執行的 CI 流程可能因此中斷。

五、密鑰存在哪

官方的警告：Inspector 會儲存一些敏感資料，包括 OAuth 令牌、OAuth 客戶端密鑰，以及 stdio 伺服器 env: 裏的值。

• 系統有鑰匙串時，存進操作系統的鑰匙串；
• 沒有鑰匙串的機器（官方列舉了缺少相應組件的 Linux、無介面和 SSH 會話、容器等）會存到 ~/.mcp-inspector/secrets.json，除非你提供密鑰，否則是不加密的。

在伺服器、容器或共享機器上用 Inspector 調試帶密鑰的服務時，要留意這個文件。

六、伺服器列表：config 與 catalog

兩者不能同時使用。官方說明 v1 時期的 mcpServers 格式文件可以原樣使用，也就是說，客戶端裏那份 MCP 配置可以直接拿來給 Inspector 讀。

七、舊教學對不上：v1 到 v2 改了什麼

想繼續用舊版：

bash
npx @modelcontextprotocol/inspector@v1-latest

官方說明 v1 這條線只接收安全修復。

八、安全提醒

• 不要關閉鑑權。帶 DANGEROUSLY_ 前綴的變量名字已經說明了風險：Inspector 能啟動本機進程，關掉令牌校驗等於讓能訪問那個端口的任何頁面或程序都能借它執行命令；
• 不要監聽到所有網卡，除非你清楚網絡環境並且做了訪問控制；
• 調試第三方伺服器等於運行它。Inspector 只是幫你啟動並連接，伺服器進程照樣以你的身份運行。來源不明的伺服器先審再跑，見《MCP 伺服器怎麼選、裝之前怎麼審》。

常見問題

Q：提示 Node 版本不滿足？

v2 要求 22.19.0 及以上。遷移文檔說明 npm 預設只是警告，除非你設了 engine-strict=true。升級 Node，或者改用 @v1-latest。

Q：打開頁面提示未授權？

用啟動時終端裏打印的那個完整地址，它帶着本次啟動的令牌。手動輸入不帶令牌的地址會被拒絕。

Q：寫 Python 伺服器時怎麼用？

官方 Python SDK 的 mcp dev server.py 會直接啟動伺服器並打開 Inspector，見《MCP Server 開發入門（Python）》。

Q：Inspector 里正常，客戶端裏不正常？

說明伺服器沒問題，問題在客戶端配置：啟動命令的路徑是否為絕對路徑、環境變量有沒有傳進去、配置文件的 JSON 是否合法。各客戶端的配置見《Claude Code MCP 配置教學》和《Claude Desktop MCP 配置》。

參考資料

• MCP Inspector（MCP 官方文檔）：https://modelcontextprotocol.io/docs/tools/inspector
• modelcontextprotocol/inspector（官方倉庫）：https://github.com/modelcontextprotocol/inspector
• v1 → v2 migration：https://github.com/modelcontextprotocol/inspector/blob/main/docs/v1-to-v2-migration.md