Comet Opik

官方

以自然語言查詢並分析您的 Opik 日誌、追蹤、提示詞，以及來自 LLM 的所有其他遙測資料。

GitHub

217

你可以用 Comet Opik MCP 做什麼？

瀏覽與搜尋你的 Opik 工作區 — 透過 list 列出專案、實驗、追蹤記錄、跨度、提示詞或測試套件，並可選用名稱篩選與分頁功能。
以 ID、名稱或 URI 檢視任何實體 — 使用 read 搭配 opik:// URI 或 UUID，擷取完整詳細資訊（包含追蹤記錄與提示詞的內嵌子項目）。
記錄追蹤、評分、評論與提示詞版本 — 透過 write 建立或更新追蹤記錄與跨度、附加回饋評分、儲存提示詞版本，以及管理測試套件。
向 Ollie 提出關於 LLM 可觀測性資料的調查問題 — 查詢 ask_ollie 以比較實驗、診斷回歸問題，或綜合跨實體的洞察，並可選用中段評分功能。
端到端執行評估實驗 — 使用 run_experiment 觸發實驗，搭配提示詞、測試套件與評分器，以執行並記錄完整的評估流程。
檢視寫入操作的結構定義 — 使用 schema 在構建承載前，擷取任何寫入操作的確切 JSON 結構與必要欄位。

文件

Opik MCP 伺服器

官方模型上下文協定 (MCP) 伺服器，適用於 Opik，這是由 Comet 打造的開源 LLM 可觀測性與評估平台。 將您的 AI 主機（Claude Code、Cursor、VS Code Copilot、MCP Inspector）直接連接到您的 Opik 工作區：讀取追蹤記錄、記錄評分、儲存提示版本，並向 Opik 的內建 AI 助理 Ollie 提出調查性問題，一切都在聊天中完成。

專為已在執行 Opik 並希望從他們編碼時使用的同一個 AI 助理來驅動它的 LLM 工程師所打造。

從舊的 npx opik-mcp 遷移？ TypeScript 伺服器已棄用，並將於 2026-11-15 終止服務。在您的 MCP 用戶端設定中，將 npx -y opik-mcp 替換為 uvx opik-mcp@latest。完整指南：legacy/typescript/MIGRATION.md。

You:    "Why did the experiment 'gpt-4o-rerank-v3' regress on factuality?"
Claude: → ask_ollie → reads experiment + traces → "Three traces failed because…"

You:    "Score trace 7f2e… 0.9 on helpfulness with reason 'great recovery'."
Claude: → write(score.create) → done

安裝

opik-mcp 是一個 Python 套件（需要 Python 3.13+）。建議的執行方式是使用 uvx，它會按需擷取並執行最新發布的版本 — 無需全域安裝，無需管理虛擬環境。

一次性安裝 uv：

curl -LsSf https://astral.sh/uv/install.sh | sh   # macOS / Linux
# or: brew install uv

您需要從 Opik 工作區取得兩項資訊：

OPIK_API_KEY — 從 comet.com/api/my/settings/ 取得。
OPIK_WORKSPACE — 您的工作區名稱（小寫，如同在 URL 中顯示）。例如 https://www.comet.com/acme-ai/... → OPIK_WORKSPACE=acme-ai。選用 — 預設為 default（Opik SDK 慣例），這對於本機/OSS 安裝是正確的；使用具名工作區的雲端使用者應設定它。COMET_WORKSPACE 可作為已棄用的別名使用。

預發布注意事項： opik-mcp（Python）尚未發布到 PyPI。在首次 PyPI 發布上線之前，請將下方任何程式碼片段中的 uvx opik-mcp 替換為： uvx --from git+https://github.com/comet-ml/opik-mcp.git opik-mcp

OPIK_WORKSPACE 是選用的。 在下方任何程式碼片段中省略 OPIK_WORKSPACE 行/鍵，伺服器將使用 default 工作區（對於本機/OSS 安裝是正確的）。僅在您連接到具名雲端工作區時才設定它。

Claude Code

用一個指令新增伺服器：

claude mcp add --transport stdio opik-mcp \
  --env OPIK_API_KEY=<your-key> \
  --env OPIK_WORKSPACE=<your-workspace> \
  -- uvx opik-mcp

或直接編輯 ~/.claude.json：

{
  "mcpServers": {
    "opik-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["opik-mcp"],
      "env": {
        "OPIK_API_KEY": "<your-key>",
        "OPIK_WORKSPACE": "<your-workspace>"
      }
    }
  }
}

重新啟動 Claude Code。使用 /mcp 驗證 — opik-mcp 應顯示為已連線。然後，在聊天中詢問："列出我的 Opik 專案" — Claude 將呼叫 list 工具，您將看到工作區的專案。

Cursor

編輯 ~/.cursor/mcp.json（全域）或 .cursor/mcp.json（專案），或開啟 Cmd+Shift+J → 功能 → 模型上下文協定：

{
  "mcpServers": {
    "opik-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["opik-mcp"],
      "env": {
        "OPIK_API_KEY": "<your-key>",
        "OPIK_WORKSPACE": "<your-workspace>"
      }
    }
  }
}

重新載入 Cursor；MCP 面板中 opik-mcp 旁的綠點確認連線。在聊天中詢問："列出我的 Opik 專案"。

Cursor 60 秒逾時。 Cursor 強制執行硬性工具呼叫逾時，該逾時不會因進度通知而重置。長時間的 ask_ollie 回合將在 Cursor 上失敗。請參閱已知主機限制。

VS Code Copilot

在您的工作區（或使用者設定 JSON）中設定 .vscode/mcp.json：

{
  "servers": {
    "opik-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["opik-mcp"],
      "env": {
        "OPIK_API_KEY": "<your-key>",
        "OPIK_WORKSPACE": "<your-workspace>"
      }
    }
  }
}

重新載入視窗；一旦伺服器可連線，Copilot Chat 的 MCP 指示器會顯示 opik-mcp。在聊天中詢問："列出我的 Opik 專案"。

MCP Inspector（手動測試）

OPIK_API_KEY=<your-key> OPIK_WORKSPACE=<your-workspace> \
  npx @modelcontextprotocol/inspector uvx opik-mcp

自託管 Opik

將 COMET_URL_OVERRIDE（以及如果 Opik 位於非預設路徑，則加上 OPIK_URL）新增到您主機設定中的同一個 env 區塊：

{
  "mcpServers": {
    "opik-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["opik-mcp"],
      "env": {
        "OPIK_API_KEY": "<your-key>",
        "COMET_URL_OVERRIDE": "https://opik.your-company.com",
        "OPIK_MCP_ANALYTICS_SOURCE": ""
      }
    }
  }
}

ask_ollie 和 run_experiment 僅在 Comet Cloud 上可用 — 在自託管環境中，這些呼叫在派送時會失敗，因此請直接使用 read / list / write。設定 OPIK_MCP_ANALYTICS_SOURCE="" 會讓您的安裝在遙測事件中選擇退出 cloud-Comet 來源標籤。

工具

opik-mcp 公開了一個小巧、以結果為導向的操作介面 — 六個工具涵蓋了完整的生命週期（讀取 → 註解 → 策展 → 編寫 → 迭代）。

工具	用途
`read`	透過 ID / 名稱 / `opik://` URI 進行通用讀取
`list`	帶有可選名稱篩選器和分頁的通用列表
`ask_ollie`	透過 Opik 內建助理進行調查 / 綜合分析
`write`	通用寫入 — 記錄追蹤/跨度、評分、評論、儲存提示、管理測試套件和實驗
`schema`	內省寫入操作結構描述（由 LLM 用於建構有效的酬載）
`run_experiment`	透過 Ollie 端對端執行評估實驗

`read`

一個工具處理任何「顯示 X 給我看」的問題。接受一個 entity_type 加上一個 id （UUID 或，對於可命名類型，一個名稱）或一個完整的 opik:// URI。複合讀取（trace、prompt）會內聯其子項，因此單次呼叫即可返回完整畫面。

支援的實體： project、trace、span、test_suite、experiment、 prompt。基於名稱的查詢適用於 project、experiment、prompt、 test_suite（較慢 — 兩次 API 呼叫 — 且可能返回多個匹配項）。

read(entity_type="trace", id="7f2e3c8a-…")
read(entity_type="project", id="demo")          # name lookup
read(entity_type="trace", id="opik://traces/7f2e3c8a-…")

`list`

使用可選的名稱篩選器和分頁來瀏覽集合。專案範圍的類型（trace、test_suite_item、prompt_version）需要其父項 UUID。

list(entity_type="experiment", page=1, size=25)
list(entity_type="experiment", name="rerank")          # name substring filter
list(entity_type="trace", project_id="<project-uuid>") # traces of one project

`ask_ollie`

用於調查性問題、跨實體綜合分析，或任何需要 Opik 領域專業知識的事務。Ollie 對您的工作區具有直接讀取權限，並且可以在被要求時，於流程中執行寫入（評分、評論、測試套件項目、提示版本）。

ask_ollie(query="Why are spans in project 'demo' slower this week than last?")
ask_ollie(query="Compare experiments A and B on factuality. Score the bottom 5 traces of A 0.2 with reason.")

返回助理的最終文字以及一個 thread_id。在後續追問時將其傳回以保留上下文 — Ollie 在不同對話串之間沒有記憶。

YOLO 模式（預設）。 Ollie 在流程中執行的寫入操作無需每次操作確認即可執行。每個自動核准都會作為 JSON 稽核行記錄在 opik_mcp.audit Python 記錄器上。若要改為要求確認，請設定 OPIK_MCP_AUTO_APPROVE=disabled — Ollie 的確認請求隨後會顯示為您可以手動重新發出的類型化錯誤。

僅在 Comet Cloud 上可用。

`write`

通用寫入派送器。傳遞 operation + data，派送器會驗證酬載，套用正確的 REST 動詞，並返回後端回應。

操作：

操作	作用
`trace.create`	記錄單一追蹤（或批次）。作為跨度 / 評分 / 評論的父項。
`trace.update`	完成或修改現有追蹤。
`span.create`	在現有追蹤上記錄一個跨度（或批次）。
`score.create`	將數值回饋評分附加到追蹤、跨度或對話串。
`comment.create`	將自由文字評論附加到追蹤、跨度或對話串。
`prompt_version.save`	儲存新的提示版本（若不存在則按名稱建立提示）。
`test_suite.create`	建立評估測試套件。
`test_suite_item.upsert`	將項目更新插入到測試套件中（始終使用信封形狀）。
`experiment.create`	建立一個限定於測試套件的實驗。
`experiment_item.create`	將追蹤 + 資料集項目列附加到實驗。

write(operation="score.create", data={
  "target": "trace",
  "target_id": "7f2e3c8a-…",
  "name": "helpfulness",
  "value": 0.9,
  "reason": "great recovery"
})

`schema`

在呼叫任何寫入操作之前，檢查其確切的 JSON 形狀和必要欄位 — 當您不確定 data 應該是什麼樣子時很有用。返回結構描述、OAuth 範圍和一個經過驗證的範例。純查詢，無後端呼叫。

schema(operation="score.create")
schema(operation="prompt_version.save")

`run_experiment`

透過 Ollie 端對端執行評估實驗。接受一個單一的 experiment_config 字典，該字典反映了 Opik 的實驗形狀（提示、測試套件、評分器）；Ollie 執行運行並將結果寫回為一個 Opik 實驗。

run_experiment(experiment_config={
  "test_suite_name": "qa-eval-v2",
  "prompt_name": "welcome-msg",
  # … see `schema(operation="experiment.create")` for the full shape
})

僅在 Comet Cloud 上可用。

設定

每個設定都是一個環境變數。必要項以粗體顯示。

身分 / 端點

變數	預設值	備註
`OPIK_API_KEY`	—	`ask_ollie` 和任何已驗證的讀取/寫入所需。
`OPIK_WORKSPACE`	`default`	工作區名稱。選用 — 回退到 `default`（Opik SDK 慣例）。使用具名工作區的雲端使用者應設定它。
`COMET_WORKSPACE`	—	`OPIK_WORKSPACE` 的已棄用別名（向後相容）。若兩者皆設定，則 `OPIK_WORKSPACE` 優先。
`COMET_WORKSPACE_ID`	—	選用的工作區 UUID。設定後會標記到分析事件中，以便 BI 可以根據穩定的 ID 而非（可變的）工作區名稱進行關聯。
`COMET_URL_OVERRIDE`	`https://www.comet.com`	設定為您的自託管 Comet 主機，或用於暫存環境的 `https://dev.comet.com`。
`OPIK_URL`	衍生自 `COMET_URL_OVERRIDE` + `/opik/api`	僅在 Opik 位於與 Comet UI 不同的主機/路徑時才覆寫。
`OPIK_DEFAULT_PROJECT_NAME`	未設定	設定後，每個工作階段的 `instructions` blob 會告訴 LLM 在每次工具呼叫時將此作為 `project_name` 傳遞，除非使用者指定了不同的專案。

伺服器 / 傳輸

變數	預設值	備註
`OPIK_MCP_TRANSPORT`	`stdio`	主機啟動時為 `stdio`，監聽連接埠時為 `streamable-http`。
`OPIK_MCP_HOST`	`127.0.0.1`	uvicorn 繫結主機（僅限 `streamable-http`）。
`OPIK_MCP_PORT`	`8080`	uvicorn 繫結連接埠（僅限 `streamable-http`）。
`OPIK_MCP_RELOAD`	`false`	設定為 `true` 以啟用 uvicorn `--reload`（僅限開發）。
`OPIK_MCP_AS_URL`	未設定	OAuth 授權伺服器 URL，在 `/.well-known/oauth-protected-resource`（RFC 9728）中公告，並用作 AS-discovery 探測的代理目標。MCP 主機透過 HTTP 啟動 OAuth 流程所需。
`OPIK_MCP_RESOURCE_URI`	未設定	此伺服器的標準公開 URI，在受保護資源元資料中公告為 `resource`，並用於衍生 `WWW-Authenticate` 提示。
`OPIK_MCP_LOG_LEVEL`	`INFO`	stderr 記錄器閾值。

選擇傳輸方式

opik-mcp 在 HTTP 傳輸上不執行本機憑證驗證：任何格式正確的 Authorization: Bearer …（Opik API 金鑰或 opik_mcp_at_… OAuth 存取權杖）都會被原封不動地轉發到 opik-backend，後者是單一的授權執行點。根據部署形式選擇傳輸方式：

情境	傳輸方式
MCP 用戶端和 Opik 在同一台機器上（本機 OSS 安裝）	stdio（建議 — 最簡單，無連接埠，無需 OAuth 設定）
本機 MCP 用戶端 → 遠端 Opik（Comet cloud / 自託管）	使用 `OPIK_API_KEY` 的 stdio，或使用 OAuth 的 HTTP（`OPIK_MCP_AS_URL` 指向後端）
託管的 opik-mcp 與 opik-backend 位於相同的邊緣後方	HTTP — 承載者由後端根據每個請求進行驗證

本機 OSS 安裝注意事項：OSS 後端不會驗證請求，因此位於其前方的 HTTP opik-mcp 與 OSS REST API 本身一樣開放。在共享網路上，請保持預設的 127.0.0.1 繫結（並優先使用 stdio）。

Ollie / 長時間呼叫

變數	預設值	備註
`OPIK_MCP_AUTO_APPROVE`	`enabled`	設定為 `disabled` 以要求 Ollie 的流程中寫入在繼續之前需獲得每次操作核准。在公告 MCP `elicitation` 能力的主機上，使用者會看到是/否提示；在較簡單的主機上，請求會顯示為您可以手動重新發出的類型化錯誤。
`OPIK_MCP_ELICIT_TIMEOUT_SECONDS`	`60`	Ollie 的流程中確認提示在被視為取消之前，可以等待使用者的時間長度。`0` 停用此限制（僅限偵錯）。
`OPIK_MCP_POD_READY_TIMEOUT_S`	`120`	Ollie Pod 冷啟動輪詢上限。
`OPIK_MCP_POD_READY_INTERVAL_S`	`2`	冷啟動輪詢間隔。
`OPIK_MCP_HEARTBEAT_INTERVAL_S`	`15.0`	看門狗節奏 — 當 Pod 靜默時發出 `notifications/progress` 滴答聲，以防止主機逾時。
`OPIK_MCP_STREAM_IDLE_TIMEOUT_S`	`300.0`	Pod 靜默的硬性上限，超過後 `ask_ollie` 會中止。`0` 停用（僅限偵錯）。

遙測

匿名使用事件（僅事件類型與時間 — 不含查詢內容）。系統會包含您 API 金鑰的 SHA-256 摘要，以便支援團隊查找您的帳戶；原始金鑰絕不會離開處理程序。選擇退出： OPIK_MCP_ANALYTICS_ENABLED=false。

變數	預設值	備註
`OPIK_MCP_ANALYTICS_ENABLED`	`true`	設為 `false` 可停用所有遙測。
`OPIK_MCP_ANALYTICS_URL`	`https://stats.comet.com/notify/event/`	用於預備環境的覆寫設定。
`OPIK_MCP_ANALYTICS_ENVIRONMENT`	`prod`	每個事件上的標籤（`prod` / `staging` / `dev`）。
`OPIK_MCP_ANALYTICS_SOURCE`	`comet.com`	接收端使用此值來標記 `on_prem=False`。地端安裝應覆寫為 `""` 或自有網域。
`OPIK_MCP_ANALYTICS_CONNECT_TIMEOUT_S`	`5.0`	HTTP 連線逾時。
`OPIK_MCP_ANALYTICS_TOTAL_TIMEOUT_S`	`10.0`	HTTP 請求總逾時。

已知的主機限制

MCP 規範允許主機在 notifications/progress 上重設其工具呼叫逾時 — opik-mcp 會針對每個 Ollie SSE 事件發出一個，外加一個 15 秒的看門狗心跳。實際情況參差不齊：

Claude Code — 無文件記載的工具呼叫逾時；心跳會讓呼叫保持活躍直到 message_end。建議使用。
Cursor — 強制 60 秒逾時，且不會在進度更新時重設（上游錯誤）。長時間的 Ollie 回合將會失敗。請保持 ask_ollie 查詢聚焦。
MCP Inspector — MAX_TOTAL_TIMEOUT 限制了總持續時間（預設 60 秒）。對於長時間操作，請在 Inspector UI 中提高此值。

如果呼叫卡住，請設定 OPIK_MCP_LOG_LEVEL=DEBUG — 心跳失敗（通常是主機斷線）會以除錯層級記錄在 opik_mcp.ask_ollie。

疑難排解

OPIK_API_KEY is required to use ask_ollie — 該變數未送達伺服器程序。在 Claude Code / Cursor / VS Code 中，環境變數僅在 MCP 伺服器設定的 env 區塊內生效，而非您的 shell。編輯後請重新啟動主機。

ask_ollie 在 2 分鐘後回傳「pod 尚未就緒」 — Ollie pod 冷啟動超過了 OPIK_MCP_POD_READY_TIMEOUT_S。請重試 — 第二次呼叫通常會命中已暖機的 pod。

ask_ollie / run_experiment 在自託管的 Opik 上因派送錯誤而失敗 — 這些工具僅在 Comet Cloud 上可用。請在自託管環境中直接使用 read / list / write。

Cursor 呼叫在 60 秒時逾時 — 這是 Cursor 的已知錯誤，而非 opik-mcp。請縮短 Ollie 查詢，或在沒有強制上限的 Claude Code 上執行相同操作。

開發

git clone git@github.com:comet-ml/opik-mcp.git
cd opik-mcp
make install        # uv sync --extra dev
make check          # lint + typecheck + test
make run-dev        # uvicorn with --reload + DEBUG logs
make inspect        # MCP Inspector against the running server

常見目標：

目標	作用
`make install`	`uv sync --extra dev`
`make run`	執行 MCP 伺服器（預設為 stdio）。
`make run-dev`	以 DEBUG 日誌 + uvicorn `--reload` 執行。
`make dev`	透過 `mcp dev`（Inspector 開發模式包裝器）執行。
`make inspect`	針對執行中的伺服器啟動 MCP Inspector。
`make test`	`uv run pytest -q`。
`make test-live`	針對 `dev.comet.com` 進行即時端對端測試（設定 `OPIK_API_KEY` + `OPIK_WORKSPACE`）。
`make lint`	`ruff check` + 格式檢查。
`make format`	`ruff format` + `ruff check --fix`。
`make typecheck`	`mypy`。
`make check`	`lint + typecheck + test`。

儲存庫佈局：

opik-mcp/
├── src/opik_mcp/        ← server, tools, ask_ollie, analytics
├── tests/               ← pytest suites
├── scripts/             ← live-BE smoke + MCP-session smoke
├── legacy/typescript/   ← deprecated v2 TS server
├── pyproject.toml
└── Makefile

取得協助

提交問題以回報錯誤和功能請求
Opik 文件提供 SDK / 後端說明文件
Comet 社群 Slack 用於提問

從 v2 升級？ 舊版 TypeScript 伺服器仍以 opik-mcp@^2（npx -y opik-mcp）的名稱在 npm 上發布；原始碼保留在 legacy/typescript/ 下。請參閱 legacy/typescript/DEPRECATED.md 了解支援政策。

授權

Apache-2.0。