/ 目錄 / 演練場 / opik-mcp
● 社群 comet-ml ⚡ 即開即用

opik-mcp

作者 comet-ml · comet-ml/opik-mcp

Comet 官方 Opik MCP — 直接在 Claude 或 Cursor 中管理你的 LLM 應用程式的提示詞、專案、追蹤記錄與指標,不需要切換分頁。

Opik 是一個 LLM 可觀測性平台(提示詞、追蹤記錄、評估、資料集)。此官方 MCP 讓你的 IDE/代理程式能存取這些基本功能:列出追蹤記錄、取得提示詞、建立資料集、檢視指標。支援 Opik Cloud 或自行架設。

為什麼要用

核心特性

即時演示

實際使用效果

opik.replay ▶ 就緒
0/0

安裝

選擇你的客戶端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "opik": {
      "command": "npx",
      "args": [
        "-y",
        "opik-mcp"
      ],
      "_inferred": true
    }
  }
}

開啟 Claude Desktop → Settings → Developer → Edit Config。儲存後重啟應用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "opik": {
      "command": "npx",
      "args": [
        "-y",
        "opik-mcp"
      ],
      "_inferred": true
    }
  }
}

Cursor 使用與 Claude Desktop 相同的 mcpServers 格式。專案級設定優先於全域。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "opik": {
      "command": "npx",
      "args": [
        "-y",
        "opik-mcp"
      ],
      "_inferred": true
    }
  }
}

點擊 Cline 側欄中的 MCP Servers 圖示,然後選 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "opik": {
      "command": "npx",
      "args": [
        "-y",
        "opik-mcp"
      ],
      "_inferred": true
    }
  }
}

格式與 Claude Desktop 相同。重啟 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "opik",
      "command": "npx",
      "args": [
        "-y",
        "opik-mcp"
      ]
    }
  ]
}

Continue 使用伺服器物件陣列,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "opik": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "opik-mcp"
        ]
      }
    }
  }
}

加入 context_servers。Zed 儲存後熱重載。

claude mcp add opik -- npx -y opik-mcp

一行命令搞定。用 claude mcp list 驗證,claude mcp remove 移除。

使用場景

實戰用法: opik-mcp

將正式環境的追蹤記錄拉進 IDE,除錯錯誤的 LLM 回應

👤 LLM 應用程式開發者 ⏱ ~15 min intermediate

何時使用: 使用者回報了錯誤的答案;追蹤記錄在 Opik 中;你想在不離開 Cursor 的情況下檢查它。

前置條件
  • Opik API 金鑰 — comet.com/site > API Keys(或自行架設的管理員介面)
步驟
  1. 尋找追蹤記錄
    在專案 'prod-chatbot' 中搜尋輸出包含 'I cannot help with that' 的追蹤記錄,時間範圍為最近 24 小時。✓ 已複製
    → 符合條件的追蹤記錄 ID 與時間戳記
  2. 檢查內容
    開啟追蹤記錄 ID abc123,顯示完整的訊息鏈、呼叫的工具,以及中間的推理過程。✓ 已複製
    → 完整的追蹤記錄物件
  3. 形成假設
    為什麼模型可能拒絕回應?將此追蹤記錄與同一提示詞範本下成功的追蹤記錄進行比較。✓ 已複製
    → 差異比較與假設

結果: 透過追蹤記錄驅動的除錯流程,無需切換應用程式,提升除錯效率。

注意事項
  • 追蹤記錄中包含個人識別資訊(PII) — 在大範圍開放 MCP 存取前,先設定 Opik 的資料遮蔽功能

在版本追蹤下迭代提示詞範本

👤 提示詞工程師 ⏱ ~25 min advanced

何時使用: 你正在調整系統提示詞,並希望將每個版本儲存至 Opik 以便回滾。

步驟
  1. 取得目前版本
    取得提示詞 'support-agent-system' 的最新版本。✓ 已複製
    → 目前的提示詞內容
  2. 編輯並提交
    提出一個能更好處理升級問題的修改方案,顯示差異,並以訊息 'add escalation path' 提交為新版本。✓ 已複製
    → 差異比較與新版本 ID
  3. 對資料集執行評估
    對資料集 'support-eval-v1' 執行此新版本,比較與前一版本的通過率。✓ 已複製
    → 指標比較結果

結果: 以資料為依據進行提示詞修改,並透過版本控制管理。

注意事項
  • 缺乏防護措施——效能退步的提示詞直接進入正式環境 — 使用 Opik 的實驗框架:通過率未達基準線前不應升版

產生每週 LLM 應用程式健康報告

👤 工程主管、LLM 應用程式產品經理 ⏱ ~30 min intermediate

何時使用: 你希望在每週一早上取得成本、延遲、錯誤率和主要失敗類別的摘要。

步驟
  1. 取得上週指標
    針對專案 'prod-chatbot':取得過去 7 天的總追蹤記錄數、總 token 數、平均延遲 p50/p95、錯誤計數。✓ 已複製
    → 指標資料區塊
  2. 分類失敗原因
    抽取 20 筆失敗的追蹤記錄,依失敗模式分群,並按頻率排序各群。✓ 已複製
    → 失敗原因分類
  3. 撰寫摘要
    以 Markdown 格式撰寫包含指標與前 3 大失敗模式的摘要,可直接貼至 Slack。✓ 已複製
    → 可分享的報告

結果: 掌握每週 LLM 運維狀況,無需花時間手動查看儀表板。

注意事項
  • 隨著應用程式演進,指標定義出現偏差 — 將報告範本版本化,確保每週比較的基準一致
搭配使用: notion

組合

與其他 MCP 搭配,撬動十倍槓桿

opik + github

當提示詞效能退步時,建立包含失敗追蹤記錄的 GitHub Issue

如果 'support-eval-v1' 的通過率相較上週下降超過 5%,建立一個 GitHub Issue 並附上前 3 筆失敗的追蹤記錄 ID。✓ 已複製
opik + notion

將每週 LLM 健康摘要發布至 Notion

根據上週的 Opik 指標撰寫週一摘要,並在 'LLM Weekly' 中建立一個 Notion 頁面。✓ 已複製

工具

此 MCP 暴露的能力

工具輸入參數何時呼叫成本
list_projects workspace_id? 瀏覽你的工作區 1 API call
list_traces project, filter?, start?, end?, limit? 依時間範圍或內容尋找追蹤記錄 1 API call
get_trace trace_id 深入檢視單一追蹤記錄 1 API call
get_prompt name, version? 讀取提示詞以供編輯或在程式中使用 1 API call
create_prompt_version name, template, message? 提交新的提示詞迭代版本 1 API call
create_dataset name, items[] 建立評估資料集 1 API call
get_metrics project, metric, window 監控成本/延遲/品質 1 API call

成本與限制

運行它的成本

API 配額
Opik Cloud 依方案有用量限制;自行架設則無限制
每次呼叫 Token 數
追蹤記錄列表約 1k-5k tokens;單筆追蹤記錄約 500-3000
費用
Opik 提供慷慨的免費方案;規模化使用需付費方案。MCP 本身免費(Apache 2.0)。
提示
使用 list_traces 時務必指定時間範圍;在流量大的專案中,絕不要在沒有時間範圍的情況下呼叫。

安全

權限、密鑰、影響範圍

最小權限: Opik API key scope the workspace you intend to expose
憑證儲存: OPIK_API_KEY 環境變數;HTTP 傳輸使用 Authorization: Bearer
資料出站: 追蹤記錄可能包含含有個人識別資訊的提示詞/回應——請了解你的 Opik 資料存放區域與遮蔽設定
切勿授予: An admin-scope key to a shared dev machine

故障排查

常見錯誤與修復

401 Unauthorized (Bearer)

確認 OPIK_API_KEY 是否正確。自行架設時,還需設定 --apiUrl http://host:5173/api

驗證: curl -H 'Authorization: Bearer $KEY' $URL/api/v1/workspaces
Empty trace list despite traffic

專案或工作區選擇錯誤。請先列出所有專案並確認 UUID。

Self-hosted MCP can't reach backend

使用容器網路(同一個 docker network),或將 --apiUrl 指向外部可連線的網址。

替代方案

opik-mcp 對比其他方案

替代方案何時用它替代權衡
LangSmith MCP你使用 LangSmith 進行追蹤不同平台;功能類似
Langfuse MCP你使用 Langfuse(開源版)同樣開源且可自行架設;資料結構不同
Arize / Phoenix你希望專注於評估與漂移偵測ML 監控功能更豐富;學習曲線較陡

更多

資源

📖 閱讀 GitHub 上的官方 README

🐙 查看未解決的 issue

🔍 瀏覽全部 400+ MCP 伺服器和 Skills