Comet Opik

官方

用自然语言查询和分析你的Opik日志、追踪、提示词以及所有来自大语言模型的其他遥测数据。

GitHub

218

试用此 MCP赞助

你可以用 Comet Opik MCP 做什么？

读取任意 Opik 实体 — 通过 read 按 id、名称或 opik:// URI 获取项目、追踪、跨度、测试套件、实验或提示。
浏览集合 — 使用 list 配合名称过滤和分页列出实体，如实验或项目范围内的追踪。
向 Ollie 提出调查性问题 — 将关于延迟、回归或比较的跨实体问题发送至 ask_ollie 进行综合分析。
记录分数和评论 — 通过 write 操作（如 score.create）将数值反馈分数或自由文本评论附加到追踪、跨度或线程。
保存提示版本 — 通过 write(operation="prompt_version.save") 保存新版本以创建或更新提示。
运行评估实验 — 通过 Ollie 使用 run_experiment 执行端到端评估实验，利用测试套件、提示和评分器。

文档

Opik MCP 服务器

官方为 Opik 打造的 Model Context Protocol (MCP) 服务器——开源 LLM 可观测性与评估平台，由 Comet 构建。 将你的 AI 宿主（Claude Code、Cursor、VS Code Copilot、MCP Inspector）直接接入你的 Opik 工作区：读取追踪、记录评分、保存提示词版本，以及向 Ollie（Opik 内置的 AI 助手）提出调查性问题，一切尽在聊天中完成。

专为已经使用 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。COMET_WORKSPACE 作为弃用别名仍然可用。

云端，使用 API 密钥时：除非你的账户默认工作区正是所需，否则请设置此项。 如果留空，服务器会发送 default，Comet 会将其解析为你账户的默认工作区。这虽然可行，但如果你实际上在某个命名工作区中工作，你会在毫无提示的情况下被指向另一个工作区——读取结果来自错误的位置，而不是直接报错。

云端，通过 OAuth：保持未设置。 工作区来自你授权的令牌，服务器会完全忽略此设置。

本地 / 开源版：保持未设置。 开源版 Opik 只有名为 default 的单个工作区，且无法创建其他工作区，这正是回退机制给你的结果。

自托管 Comet：请设置。 与开源版不同，这些部署拥有真正的命名工作区，同样存在静默指向错误工作区的风险。

无论属于哪种情况，请确保该值确实被替换了。网络上流传的配置片段带有 <your-workspace> 或 ${input:OPIK_WORKSPACE} 之类的占位符；如果原样粘贴，这些并不是工作区名称。服务器现在会直接拒绝它们，而不是让后端返回一个毫无解释的认证错误。

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 → Features → Model Context Protocol：

{
  "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

在工作区中添加 .vscode/mcp.json（或用户设置 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>",
        "OPIK_WORKSPACE": "<your-workspace>",
        "COMET_URL_OVERRIDE": "https://opik.your-company.com",
        "OPIK_MCP_ANALYTICS_SOURCE": ""
      }
    }
  }
}

在开源部署中省略 OPIK_WORKSPACE，因为那里 default 是唯一的工作区；在自托管 Comet 上则保留，因为那里有真正的命名工作区。

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`	将 trace + dataset_item 行附加到实验。

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`	unset	工作区名称。在云端使用 API 密钥时，未设置会发送 `default`，它会解析为你账户的默认工作区——如果你在另一个工作区工作，请显式设置，否则读取会静默地来自错误的工作区。在 OAuth 下保持未设置（令牌已包含它），在本地/OSS 下也保持未设置（`default` 是那里唯一的工作区）。
`COMET_WORKSPACE`	—	`OPIK_WORKSPACE` 的弃用别名（向后兼容）。如果两者都设置了，`OPIK_WORKSPACE` 优先。
`COMET_WORKSPACE_ID`	unset	可选的工作区 UUID。设置后会被写入分析事件中，并优先于解析出的工作区。很少需要——OAuth 安装会自动从令牌获取 UUID。
`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`	unset	设置后，每会话的 `instructions` 块会告知 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`	unset	OAuth 授权服务器 URL，在 `/.well-known/oauth-protected-resource`（RFC 9728）中通告，并用作 AS 发现探测的代理目标。MCP 宿主通过 HTTP 启动 OAuth 流程时需要。
`OPIK_MCP_RESOURCE_URI`	unset	此服务器的规范化公共 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 云端 / 自托管）	带 `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`	在 `ask_ollie` 中止之前，pod 静默的硬上限。`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 not ready” — 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。