/ 目录 / 演练场 / opik-mcp
● 社区 comet-ml ⚡ 即开即用

opik-mcp

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

Comet 官方的 Opik MCP——在 Claude 或 Cursor 里直接管理 LLM 应用的 prompt、项目、trace 和指标,无需切换标签页。

Opik 是 LLM 可观测性平台(prompt、trace、eval、数据集)。这个官方 MCP 让你的 IDE / agent 能访问这些核心功能:列出 trace、拉取 prompt、创建数据集、查看指标。支持 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

把生产 trace 拉到 IDE 里,调试错误的 LLM 响应

👤 LLM 应用开发者 ⏱ ~15 min intermediate

何时使用: 用户报告了错误的回答;trace 在 Opik;你想在不离开 Cursor 的情况下检查它。

前置条件
  • Opik API key — comet.com/site > API Keys(或自部署管理员)
步骤
  1. 查找 trace
    在 'prod-chatbot' 项目中搜索输出包含 'I cannot help with that' 的 trace。最后 24 小时。✓ 已复制
    → 匹配的 trace ID + 时间戳
  2. 检查
    打开 trace ID abc123。给我展示完整的消息链、调用的工具和中间的推理过程。✓ 已复制
    → 完整的 trace 对象
  3. 形成假设
    模型为什么可能拒绝了?把这个 trace 与相同 prompt 模板上的成功 trace 进行对比。✓ 已复制
    → Diff + 假设

结果: 更快的基于 trace 的调试,无需切换应用。

注意事项
  • Trace 中的个人身份信息 — 在广泛启用 MCP 访问之前,配置 Opik 的信息抹除功能

使用版本跟踪迭代 prompt 模板

👤 Prompt 工程师 ⏱ ~25 min advanced

何时使用: 你在调优系统 prompt,想要每个版本都保存在 Opik 里以便回滚。

步骤
  1. 拉取当前版本
    获取 'support-agent-system' prompt 的最新版本。✓ 已复制
    → 当前 prompt 内容
  2. 编辑并提交
    提出更好地处理升级的改动。显示 diff。提交为新版本,消息为 'add escalation path'。✓ 已复制
    → Diff + 新版本 ID
  3. 对数据集进行评估
    在 'support-eval-v1' 数据集上运行这个新版本。对比通过率 vs 之前的版本。✓ 已复制
    → 指标对比

结果: 数据驱动的 prompt 变更,版本受控。

注意事项
  • 没有保护措施——一个回退的 prompt 变成了生产环境 — 使用 Opik 的实验框架:直到通过率 ≥ 基线才推广

生成每周 LLM 应用健康报告

👤 工程 lead、LLM 应用 PM ⏱ ~30 min intermediate

何时使用: 你想要一份周一早上的摘要,包括成本、延迟、错误率和最常见的失败类别。

步骤
  1. 拉取上周的指标
    对于 'prod-chatbot' 项目:总 trace 数、总 token 数、平均延迟 p50/p95、错误数——过去 7 天。✓ 已复制
    → 指标数据块
  2. 分类失败情况
    采样 20 个失败的 trace。按失败模式聚类。按频率排序。✓ 已复制
    → 失败分类表
  3. 编写摘要
    编写 Markdown 摘要,包含指标和排名前 3 的失败模式,可直接用于 Slack。✓ 已复制
    → 可分享的报告

结果: 每周的 LLM 运维感知,无需手动查看仪表板。

注意事项
  • 随着应用演进,指标漂移 — 对报告模板进行版本控制;逐周进行苹果对苹果的对比
搭配使用: notion

组合

与其他 MCP 搭配,撬动十倍杠杆

opik + github

当 prompt 回退时,用失败的 trace 打开一个 GitHub issue

如果 'support-eval-v1' 的通过率相比上周下降 >5%,用排名前 3 的失败 trace ID 创建一个 GitHub issue。✓ 已复制
opik + notion

将每周 LLM 健康摘要发布到 Notion

从上周的 Opik 指标编写周一摘要,并在 'LLM Weekly' 创建一个 Notion 页面。✓ 已复制

工具

此 MCP 暴露的能力

工具输入参数何时调用成本
list_projects workspace_id? 浏览你的 workspace 1 API call
list_traces project, filter?, start?, end?, limit? 按时间范围或内容查找 trace 1 API call
get_trace trace_id 深入查看单个 trace 1 API call
get_prompt name, version? 读取 prompt 进行编辑或在代码中使用 1 API call
create_prompt_version name, template, message? 提交一个新的 prompt 迭代 1 API call
create_dataset name, items[] 构建 eval 数据集 1 API call
get_metrics project, metric, window 监控成本 / 延迟 / 质量 1 API call

成本与限制

运行它的成本

API 配额
Opik Cloud 按计划有限制;自部署无限制
每次调用 Token 数
Trace 列表 1k-5k token;单个 trace 500-3000
费用
Opik 有一个慷慨的免费层;付费计划用于规模化。MCP 本身是免费的(Apache 2.0)。
提示
使用 list_traces 加时间窗口;在忙碌的项目上永远不要不带范围地调用。

安全

权限、密钥、影响范围

最小权限: Opik API key 范围应限于你想暴露的 workspace
凭据存储: OPIK_API_KEY 环境变量;HTTP 传输使用 Authorization: Bearer
数据出站: Trace 可能包含含有个人身份信息的 prompt / 响应——了解你的 Opik 地区和信息抹除设置
切勿授予: 不要把管理员范围的 key 给共享开发机器

故障排查

常见错误与修复

401 Unauthorized (Bearer)

检查 OPIK_API_KEY。对于自部署,也设置 --apiUrl http://host:5173/api

验证: curl -H 'Authorization: Bearer $KEY' $URL/api/v1/workspaces
尽管有流量但 trace 列表为空

项目 / workspace 错误。首先列出项目并确认 UUID。

自部署 MCP 无法连接到后端

使用容器网络(同一 docker 网络)或将 --apiUrl 映射到外部可访问的 URL。

替代方案

opik-mcp 对比其他方案

替代方案何时用它替代权衡
LangSmith MCP你使用 LangSmith 进行 trace不同的平台;功能类似
Langfuse MCP你使用 Langfuse(开源)也是开源 + 可自部署;不同的数据模式
Arize / Phoenix你想关注 eval + 漂移检测更丰富的 ML 监控功能;学习曲线更陡

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills