How to add Opik MCP to Claude Desktop

Drive your Opik LLM-observability workspace from your AI host — read traces, log scores, save prompts, ask Ollie. Paste the config into ~/Library/Application Support/Claude/claude_desktop_config.json and restart Claude Desktop.

Last updated June 14, 2026 · 210★ · stdio · apikey · official

Claude Desktop config for Opik MCP

uvx opik-mcp

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

Requires `uv` (the Python package runner). Install it from https://docs.astral.sh/uv/ if `uvx` is not found.

Setup steps

1Open Claude Desktop → Settings → Developer → Edit Config (this opens ~/Library/Application Support/Claude/claude_desktop_config.json).
2Paste the Opik MCP config below under the top-level "mcpServers" key.
3Fill in any placeholder secrets (API keys, paths) in the snippet.
4Save the file, then fully quit and reopen Claude Desktop.
5Open a chat and confirm Opik MCP's tools appear under the 🔌 tools menu.

Before you start

Python 3.13+
uv (the uvx runner) installed
An Opik / Comet workspace with an OPIK_API_KEY (from comet.com/api/my/settings/)
OPIK_WORKSPACE (optional; defaults to 'default' — set it only for a named cloud workspace)
ask_ollie and run_experiment require Comet Cloud (not available on self-hosted Opik)

What Opik MCP can do in Claude Desktop

read

Universal read by id, name, or opik:// URI. Supports project, trace, span, test_suite, experiment, and prompt entities; composite reads (trace, prompt) inline their children so one call returns the full picture. Name-based lookup is available for project, experiment, prompt, and test_suite.

list

Universal list of a collection with an optional name-substring filter and pagination. Project-scoped types (trace, test_suite_item, prompt_version) require their parent UUID.

ask_ollie

Investigate, synthesize, or cross-reference entities via Ollie, the Opik in-product assistant. Ollie has direct read access to the workspace and can execute writes (scores, comments, test-suite items, prompt versions) mid-stream when asked. Returns final text plus a thread_id for follow-ups. Comet Cloud only.

write

Universal write dispatcher. Pass operation + data; supported operations: 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. Validates the payload, applies the right REST verb, and returns the backend response.

schema

Introspect the exact JSON shape and required fields of any write operation before calling it. Returns the schema, OAuth scope, and one validated example. Pure lookup — no backend call.

run_experiment

Run an evaluation experiment end-to-end via Ollie. Takes a single experiment_config dict (prompt, test suite, scorers) mirroring Opik's experiment shape; Ollie executes the run and writes results back as an Opik experiment. Comet Cloud only.

Security

Requires OPIK_API_KEY (from comet.com/api/my/settings/) passed via the host config env block, not the shell. On HTTP transport opik-mcp performs no local credential validation — any well-formed Authorization: Bearer token is forwarded verbatim to opik-backend, which is the single point of auth enforcement; keep the default 127.0.0.1 bind and prefer stdio on shared networks. The OSS backend does not authenticate requests, so an HTTP opik-mcp in front of it is as open as the OSS REST API. Anonymous usage telemetry (event type + timing, plus a SHA-256 digest of the API key — raw key never leaves the process) is on by default; opt out with OPIK_MCP_ANALYTICS_ENABLED=false. Ollie runs in YOLO mode by default, auto-approving mid-stream writes (logged on the opik_mcp.audit logger); set OPIK_MCP_AUTO_APPROVE=disabled to require per-action confirmation. Pre-release: not yet on PyPI — use the git source form (uvx --from git+https://github.com/comet-ml/opik-mcp.git opik-mcp) until the first PyPI release.

Opik MCP + Claude Desktop FAQ

Where is the Claude Desktop config file?

Claude Desktop reads MCP servers from ~/Library/Application Support/Claude/claude_desktop_config.json. Paste the Opik MCP config there under the "mcpServers" key and restart the client.

Is Opik MCP safe to use with Claude Desktop?

How do I run it — is it on PyPI?

Run it with uvx (no global install). It is currently pre-release and not yet on PyPI; until the first PyPI release lands, replace 'uvx opik-mcp' in any snippet with 'uvx --from git+https://github.com/comet-ml/opik-mcp.git opik-mcp'.

Do all six tools work on self-hosted Opik?

No. ask_ollie and run_experiment are available on Comet Cloud only and will fail at dispatch on self-hosted. Use read / list / write directly on self-hosted (set COMET_URL_OVERRIDE to your host).

My OPIK_API_KEY isn't being picked up — why?

In Claude Code / Cursor / VS Code, env vars only apply when placed inside the 'env' block of the MCP server config, not from your shell. Add OPIK_API_KEY there and restart the host.

View repo Full Opik MCP page