← 返回目录

Opik MCP Server

官方

将你的 AI 宿主直接接入 Opik 工作区，读取追踪、记录评分、管理提示词。

查看安装方法 ↓ 横向对比 GitHub 源仓库 ↗

分类: 开发工具第 26 / 438
Stars: ★ 220 非常热门
传输方式: stdio（本地进程） · Streamable HTTP
运行环境: Python 3.13+
凭据: 需要 API Key / 凭据
许可证: Apache-2.0
最近提交: 4 天前
工具数: 6

67FMRS · C

Opik MCP Server 是 Opik 的官方 MCP 服务器，专为 LLM 可观测性和评估设计，提供丰富的工具集和良好的客户端支持。功能全面，但部分高级功能受限，且安全配置需谨慎。

最强项 · 维护活跃度 18/20 最弱项 · 可靠性 8/20

可靠性

8/20

安全与权限

14/20

维护活跃度

18/20

文档质量

15/20

安装易用性

12/20

查看各项评分依据

可靠性 8/20: 源码中存在 Python 测试套件（tests/ 目录在 README 中提及，但未提供具体内容），CI 工作流未直接可见。MANIFEST 声称 npm 包 [email protected] 提供 stdio 传输，但 README 表明 TypeScript 服务器已弃用，主服务器为 Python 且尚未发布到 PyPI（需从 git 安装）。这种不一致导致启动路径不清晰。服务器工具声明为 read、list、ask_ollie、write、schema 和 run_experiment，与 README 匹配；但 Python 包的实际工具实现未在源文件中验证。没有执行测试，因此无法确认初始化流程。由于缺乏可验证的 CI 流程和测试工件，可靠性评分上限为 12，此处评为 8。
安全与权限 14/20: 必需的环境变量 OPIK_API_KEY 被标记为机密，文档说明从进程外传递，且不记录查询内容。telemetry 部分披露了使用 API key 的 SHA-256 摘要，并说明原始 key 从不离开进程。自我托管的部署支持禁用遥测（OPIK_MCP_ANALYTICS_ENABLED=false）和覆盖遥测 URL。文档建议使用 stdio 而非 HTTP 以获得更安全的本地部署，并指出 HTTP 传输不进行本地凭据验证，但授权由后端强制执行。未发现明显恶意模式或不可逆操作的默认值。没有发现默认启用危险功能（如自动部署）的情况，但网络调用和遥测功能需要明确的用户许可。有文档说明的确认机制（OPIK_MCP_AUTO_APPROVE），但默认是自动批准，这会导致权限过高的风险。安全评分为 14，扣分原因是自动批准默认值以及遥测外部网络流量的潜在数据泄漏。
维护活跃度 18/20: 仓库活跃，有 216 颗星、32 个未解决问题、未归档。采用 Apache-2.0 许可证。有明确的变更计划和弃用时间线（TypeScript 服务器将于 2026-11-15 弃用，Python 版本正在开发中）。定期提交和发布的证据存在，但未直接显示提交频率。有多种支持的客户端（Claude、Cursor、VS Code）和 MCP Inspector。这些问题已公开，有支持和社区渠道（Slack、GitHub Issues）。版本 2.0.1 已随 MANIFEST 发布。维护力度强，依赖更新和发布节奏无法直接确认，但项目活跃度明显。评分为 18，扣分原因是对发布节奏和依赖更新的可验证证据有限。
文档质量 15/20: README 提供了全面的文档：安装（uvx、Claude Code、Cursor、VS Code、自托管）、工具描述（6 个工具）概述、环境变量配置（包括自托管遥测）、故障排除（常见错误，如 OPIK_API_KEY 未设置、Cursor 超时）以及从 v2 迁移的指南。示例 CLI 命令和 JSON 配置。已知限制（Cursor 60 秒超时）已有文档。但在以下方面存在差距：缺少工具参数的完整参考（依赖 schema 工具和 Ollie 知识），权限和遥测的细节尚不完整，并且缺少 Python 包当前状态的文档（在 README 中标注为预发布，但不是文档部分）。文档总体强大，评分为 15。
安装易用性 12/20: 安装说明清晰，使用 uvx 或从 git 安装。对于 Claude Code、Cursor 和 VS Code，提供了逐步配置示例。强调了 Python 3.13+ 要求。文档提供了 MCP Inspector 的安装说明。然而，由于服务器目前尚未在 PyPI 上以 Python 包形式提供（需要从 git 安装），因此安装方式有限。此外，标准流程需要预先安装 Opik 工作区、API 密钥和可能的端点配置。服务器包含多种环境变量设置，增加了配置复杂性。没有可验证的 CI 流程或已提交的端到端测试来证明安装开箱即用，因此设置评分上限为 15，此处评为 12。

静态评测 · 未实际运行收录于 2026-08-07

查看 FMRS 评分方法 →

选型与风险

能访问什么访问网络修改第三方账户数据

适合谁

已在使用 Opik 的 LLM 工程师
希望在编码环境中直接管理 LLM 可观测性的开发者
需要与 Opik 平台深度集成的工作流

不适合谁

未使用 Opik 的用户
对 LLM 可观测性不感兴趣的用户
需要离线或非云功能的用户（ask_ollie 和 run_experiment 仅限 Comet 云）

所需权限

读取 Opik 项目、追踪、跨度、测试套件、实验和提示词
写入追踪、跨度、评分、评论、提示词版本和实验
访问 Opik API 密钥（必需）

风险与副作用

需要 API 密钥，可能涉及安全风险
ask_ollie 和 run_experiment 仅限 Comet 云，自托管环境不可用
Cursor 强制 60 秒工具调用超时，长时间操作可能失败
默认 YOLO 模式自动批准 Ollie 的写入，可能产生意外修改

安装接入

准备工作

运行环境：Python 3.13+

OPIK_API_KEY 必填密钥必需的 Opik API 密钥，用于认证所有读写调用，可在 comet.com/api/my/settings/ 获取。

其他可选配置项（25 个）

OPIK_WORKSPACE 可选 Opik 工作区名称（可选，默认为 default）；云端具名工作区用户应设置，取自 URL 中的小写名称。

COMET_WORKSPACE 可选 OPIK_WORKSPACE 的已弃用别名；两者都设置时 OPIK_WORKSPACE 优先。

COMET_WORKSPACE_ID 可选可选的工作区 UUID，写入分析事件以便 BI 稳定关联。

COMET_URL_OVERRIDE 可选自托管 Comet 主机地址，默认 https://www.comet.com。

OPIK_URL 可选 Opik API 地址（默认由 COMET_URL_OVERRIDE 推导），仅在 Opik 位于不同主机/路径时设置。

OPIK_DEFAULT_PROJECT_NAME 可选设置后提示 LLM 在每次工具调用时默认使用该项目名。

OPIK_MCP_TRANSPORT 可选传输方式，stdio（默认）或 streamable-http。

OPIK_MCP_HOST 可选 HTTP 模式的 uvicorn 绑定主机，默认 127.0.0.1。

OPIK_MCP_PORT 可选 HTTP 模式的 uvicorn 绑定端口，默认 8080。

OPIK_MCP_RELOAD 可选开发模式下启用 uvicorn --reload，默认 false。

OPIK_MCP_AS_URL 可选 OAuth 授权服务器 URL，HTTP 模式下宿主完成 OAuth 引导所必需。

OPIK_MCP_RESOURCE_URI 可选本服务器的规范公开 URI，用于受保护资源元数据。

OPIK_MCP_LOG_LEVEL 可选 stderr 日志级别，默认 INFO；排查时设为 DEBUG。

OPIK_MCP_AUTO_APPROVE 可选 Ollie 中途写操作是否自动批准，默认 enabled；设为 disabled 要求逐项确认。

OPIK_MCP_ELICIT_TIMEOUT_SECONDS 可选 Ollie 确认提示等待用户的时间上限，默认 60 秒。

OPIK_MCP_POD_READY_TIMEOUT_S 可选 Ollie pod 冷启动轮询上限，默认 120 秒。

OPIK_MCP_POD_READY_INTERVAL_S 可选冷启动轮询间隔，默认 2 秒。

OPIK_MCP_HEARTBEAT_INTERVAL_S 可选心跳节奏，默认 15 秒，用于发送进度通知防止宿主超时。

OPIK_MCP_STREAM_IDLE_TIMEOUT_S 可选 ask_ollie 在 pod 静默多长后中止，默认 300 秒。

OPIK_MCP_ANALYTICS_ENABLED 可选匿名遥测开关，默认 true，设为 false 可关闭。

OPIK_MCP_ANALYTICS_URL 可选遥测上报地址，默认 https://stats.comet.com/notify/event/。

OPIK_MCP_ANALYTICS_ENVIRONMENT 可选环境标签（prod/staging/dev），默认 prod。

OPIK_MCP_ANALYTICS_SOURCE 可选事件来源标签，默认 comet.com；本地部署应设为空字符串。

OPIK_MCP_ANALYTICS_CONNECT_TIMEOUT_S 可选遥测 HTTP 连接超时，默认 5 秒。

OPIK_MCP_ANALYTICS_TOTAL_TIMEOUT_S 可选遥测 HTTP 总超时，默认 10 秒。

安装 uv（curl -LsSf https://astral.sh/uv/install.sh | sh）
从你的 Opik 工作区获取 OPIK_API_KEY，并可选设置 OPIK_WORKSPACE（默认为 default）
在 MCP 客户端配置中按相应格式添加服务器，使用 uvx opik-mcp 命令，并设置环境变量
重启客户端，验证连接后即可使用

.mcp.json

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

以 Claude Code 为例。其他客户端的配置文件位置或字段可能不同（如 VS Code 使用 servers 字段），可用下方配置生成器转换。

.vscode/mcp.json

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

写入项目的 .vscode/mcp.json（VS Code 使用 servers 字段）。

Terminal

claude mcp add opik-mcp -e 'OPIK_API_KEY=<your-key>' -e 'OPIK_WORKSPACE=<your-workspace>' -- uvx opik-mcp

在终端运行；先把 <…> 占位符换成你自己的值。

生成并校验客户端配置

验证是否装好

重启宿主后运行 /mcp，确认 opik-mcp 显示为已连接，然后在聊天中问 "list my Opik projects"，Claude 应调用 list 工具返回工作区项目。

常见排障

如果 `ask_ollie` 报错缺少 API 密钥，请检查环境变量是否在 MCP 客户端配置的 env 块中
如果 `ask_ollie` 长时间未响应，可能是 Ollie 冷启动，重试即可
自托管环境不支持 ask_ollie 或 run_experiment，请使用 read/list/write
Cursor 超时可尝试缩短查询或改用 Claude Code

试试这样问

连接成功后，可以直接对 AI 助手这样说：

列出我的 Opik 项目。
为什么实验 'gpt-4o-rerank-v3' 在 factuality 上退步了？
给 trace 7f2e… 打 0.9 的 helpfulness 分数，理由是 'great recovery'。
这个月项目 'demo' 里的 trace 都有哪些？

工具能力 6

read 只读

按 ID、名称或 opik:// URI 读取 Opik 实体（如项目、追踪、跨度、测试套件、实验、提示词）。

list 只读

列出 Opik 实体集合，支持名称过滤和分页。

ask_ollie 写入

通过 Opik 内置 AI 助手 Ollie 进行调查和综合分析，可回答复杂问题并执行写操作。

write 写入

通用写入操作，用于记录追踪/跨度、评分、评论、保存提示词、管理测试套件和实验。

schema 只读

查询写入操作的数据结构、必需字段和示例，帮助构建有效请求。

run_experiment 写入

通过 Ollie 端到端运行评估实验，并将结果写回 Opik。

使用场景

快速查询项目、追踪和跨度详情

为追踪或跨度添加评分和评论，用于评估

保存和版本化提示词

通过 Ollie 分析实验回归原因

运行评估实验并查看结果

支持客户端

Claude Code

Cursor部分支持

VS Code

MCP Inspector部分支持

依据项目文档列出，未经本站实测。

详细介绍

Opik MCP Server 是 Opik 的官方 Model Context Protocol (MCP) 服务器，由 Comet 构建，用于连接 AI 宿主（如 Claude Code、Cursor、VS Code Copilot）与 Opik 工作区。通过会话界面，你可以读取追踪记录、记录评分、保存提示词版本，并向 Opik 内置 AI 助手 Ollie 提问，实现端到端的 LLM 可观测性与评估工作流。该服务器提供读取、列出、写入、查询、schema 检查和实验运行等工具，支持本地和云端 Opik 部署。