Opik MCP Server

What is Opik MCP Server about?

Enables developers to interact with the Opik platform through a standardized Model Context Protocol server, supporting local stdio communication and experimental Server‑Sent Events (SSE) transport for IDE integration and unified API access.

How to use Opik MCP Server?

1. Install dependencies

   git clone https://github.com/comet-ml/opik-mcp.git
   cd opik-mcp
   npm install
   npm run build
   

2. Configure – copy the example environment file and set your Opik credentials:

   cp .env.example .env
   # edit .env (OPIK_API_BASE_URL, OPIK_API_KEY, OPIK_WORKSPACE_NAME, etc.)
   

3. Start the server
   • StdIO (default, ideal for local IDE integration):

     npm run start:stdio
     

   • SSE (experimental, allows remote HTTP clients):

     npm run start:sse
     

4. Integrate with an IDE – create a .cursor/mcp.json (or equivalent) pointing to the running server, e.g.:

   {
     "mcpServers": {
       "opik": {
         "command": "node",
         "args": ["/path/to/opik-mcp/build/index.js", "--apiUrl", "https://www.comet.com/opik/api", "--apiKey", "YOUR_API_KEY", "--workspace", "default", "--debug", "true"],
         "env": {
           "OPIK_API_BASE_URL": "https://www.comet.com/opik/api",
           "OPIK_API_KEY": "YOUR_API_KEY",
           "OPIK_WORKSPACE_NAME": "default"
         }
       }
     }
   }
   

Key features of Opik MCP Server

• Prompt management – create, list, update, delete prompts.
• Project/workspace handling – organize and switch between projects.
• Trace tracking – capture and query execution traces.
• Metrics collection – record and retrieve custom metrics.
• Multiple transport mechanisms – stdio for local use, SSE for networked scenarios.
• IDE integration – ready‑to‑use configuration for Cursor and compatible editors.
• Pre‑commit quality checks – linting and testing hooks via Makefile.

Use cases of Opik MCP Server

• IDE‑centric LLM development – developers can invoke Opik functionality directly from their editor without manual API calls.
• Unified tooling – a single server acts as a gateway for prompts, traces, and metrics, simplifying orchestration scripts.
• Remote monitoring – with the experimental SSE transport, multiple clients can stream trace and metric data in real time.
• Automated testing pipelines – integrate the server into CI to validate prompt definitions and metric collection.

FAQ from Opik MCP Server

Q: Which transport should I use for production? A: The stdio transport is stable and recommended for local IDE integrations. SSE is experimental and should be used only after thorough testing.

Q: Do I need to build the project before running it? A: Yes. After installing dependencies, run npm run build to compile TypeScript sources.

Q: How do I add custom environment variables? A: Extend the .env file or provide variables in the env section of your IDE’s MCP configuration.

Q: Is there a Docker image available? A: The repository does not currently provide an official Docker image, but you can containerize the built server using a standard Node.js base image.

Q: Where can I find detailed API documentation? A: See the docs/api-reference.md file in the repository or the online documentation linked in the README.

⚠️ Notice: SSE (Server-Sent Events) transport support is currently experimental and untested. For production use, we recommend using the direct process execution approach shown in the IDE integration examples.

🚀 What is Opik MCP Server?

Opik MCP Server is an open-source implementation of the Model Context Protocol for the Opik platform. It provides a unified interface for interacting with Opik's capabilities, supporting multiple transport mechanisms for flexible integration into various environments.

You can use Opik MCP Server for:

• IDE Integration:

  • Seamlessly integrate with Cursor and other compatible IDEs
  • Provide direct access to Opik's capabilities from your development environment

• Unified API Access:

  • Access all Opik features through a standardized protocol
  • Leverage multiple transport options (stdio, SSE) for different integration scenarios

• Platform Management:

  • Manage prompts, projects, traces, and metrics through a consistent interface
  • Organize and monitor your LLM applications efficiently

Features

• Prompts Management: Create, list, update, and delete prompts
• Projects/Workspaces Management: Organize and manage projects
• Traces: Track and analyze trace data
• Metrics: Gather and query metrics data

Quick Start

Installation

Manual Installation

# Clone the repository
git clone https://github.com/comet-ml/opik-mcp.git
cd opik-mcp

# Install dependencies and build
npm install
npm run build

Configuration

Create a .env file based on the example:

cp .env.example .env
# Edit .env with your specific configuration

Starting the Server

# Start with stdio transport (default)
npm run start:stdio

# Start with SSE transport for network access (experimental)
npm run start:sse

IDE Integration

Cursor Integration

To integrate with Cursor IDE, create a .cursor/mcp.json file in your project directory with the following configuration:

{
  "mcpServers": {
    "opik": {
      "command": "/path/to/node",
      "args": [
        "/path/to/opik-mcp/build/index.js",
        "--apiUrl",
        "https://www.comet.com/opik/api",
        "--apiKey",
        "YOUR_API_KEY",
        "--workspace",
        "default",
        "--debug",
        "true"
      ],
      "env": {
        "OPIK_API_BASE_URL": "https://www.comet.com/opik/api",
        "OPIK_API_KEY": "YOUR_API_KEY",
        "OPIK_WORKSPACE_NAME": "default",
      }
    }
  }
}

Replace /path/to/node with the path to your Node.js executable and /path/to/opik-mcp with the path to your opik-mcp installation. Also replace YOUR_API_KEY with your actual Opik API key.

Available Commands

The project includes a Makefile for common operations:

# Display all available commands
make help

# Run tests
make test

# Run transport-specific tests
make test-transport

# Start the server with SSE transport (experimental)
make start-sse

# Start the server with stdio transport
make start-stdio

Transport Options

Standard Input/Output

Ideal for local integration where the client and server run on the same machine.

make start-stdio

Server-Sent Events (SSE)

Enables remote access and multiple simultaneous clients over HTTP. Note that this transport option is experimental.

make start-sse

For detailed information about the SSE transport, see docs/sse-transport.md.

Development

Testing

# Run all tests
npm test

# Run specific test suite
npm test -- tests/transports/sse-transport.test.ts

Pre-commit Hooks

This project uses pre-commit hooks to ensure code quality:

# Run pre-commit checks manually
make precommit

Documentation

• SSE Transport - Details on using the SSE transport
• API Reference - Complete API documentation
• Configuration - Advanced configuration options
• IDE Integration - Integration with Cursor IDE

Citation

If you use this project in your research, please cite it as follows:

Comet ML, Inc, Koc, V., & Boiko, Y. (2025). Opik MCP Server. Github. https://doi.org/10.5281/zenodo.15411156

Or use the following BibTeX entry:

@software{CometML_Opik_MCP_Server_2025,
  author = {{Comet ML, Inc} and Koc, V. and Boiko, Y.},
  title = {{Opik MCP Server}},
  year = {2025},
  publisher = {GitHub},
  url = {https://doi.org/10.5281/zenodo.15411156},
  doi = {10.5281/zenodo.15411156}
}

You can also find citation information in the CITATION.cff file in this repository.

License

Apache 2.0