Overview

ClearML MCP Server exposes a Model Context Protocol (MCP) layer that surfaces the full context around ClearML experiments: metadata, configuration, metrics, artifacts, logs and simple analysis derived from that data. It is designed to be a lightweight server that lets developer tools, chat assistants, and analytics workflows retrieve experiment context in a consistent, programmatic way so conversations or downstream systems can reason about experiments with richer, data-driven context.

By centralizing experiment context behind a small HTTP API (and optional WebSocket streaming), the MCP server makes it easy to augment LLM-driven assistants, monitoring dashboards, or CI pipelines with the kinds of experiment details humans normally scroll through in the ClearML UI. Developers can fetch experiment snapshots, compare runs, read config diffs, and surface metric trends without embedding ClearML SDK logic in every tool.

Features

Exposes experiment metadata, configs, tags, and environment info in JSON
Retrieves metrics, scalars, and time-series data for experiments
Lists and streams artifacts and logs (files, model checkpoints)
Provides simple analysis endpoints (e.g., top-performing runs, metric deltas)
Lightweight HTTP API with sensible routes for integration with chatbots and dashboards
Configurable ClearML server credentials via environment variables or config file
Optional WebSocket support for streaming live updates from running experiments

Installation / Configuration

Clone the repository and run the server locally or inside Docker. The server requires access to a ClearML server (on-prem or ClearML hosted) and its API credentials.

Clone repository:

git clone https://github.com/prassanna-ravishankar/clearml-mcp.git
cd clearml-mcp

Run with Python (development):

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python mcp_server.py

Run with Docker:

docker build -t clearml-mcp:latest .
docker run -d \
  -e CLEARML_API_HOST=https://clearml.yourdomain.com \
  -e CLEARML_API_ACCESS_KEY=your-access-key \
  -e CLEARML_API_SECRET_KEY=your-secret-key \
  -e MCP_PORT=5050 \
  -p 5050:5050 \
  clearml-mcp:latest

Environment variables (typical):

CLEARML_API_HOST — ClearML server URL
CLEARML_API_ACCESS_KEY — ClearML API access key
CLEARML_API_SECRET_KEY — ClearML API secret key
MCP_PORT — Port where MCP server listens (default: 5050)
MCP_LOG_LEVEL — Logging verbosity (optional)

Config file alternative:

clearml:
  api_host: https://clearml.example.com
  access_key: XXXX
  secret_key: YYYY
server:
  port: 5050
  log_level: INFO

Point the server to the config file with a CLI flag (if supported) or set environment variables.

Available Resources

The MCP server exposes endpoints to retrieve experiment and analysis data. Typical endpoints include:

Endpoint	Method	Description
/health	GET	Server health and ClearML connectivity
/experiments	GET	List experiments with basic metadata and pagination
/experiment/{id}	GET	Full experiment context: config, tags, env
/experiment/{id}/metrics	GET	Time-series and scalar metrics for the run
/experiment/{id}/artifacts	GET	List and URLs for artifacts attached to the run
/search	POST	Search experiments by tag, metric thresholds, or text
/compare	POST	Compare two or more runs and return diffs
/analysis/top-runs	GET	Simple analysis: top N runs for a metric
/stream/{id}	WS	WebSocket for streaming logs/metrics from running experiment

Example: fetch an experiment via curl

curl -s -H "Authorization: Bearer <token>" \
  http://localhost:5050/experiment/1234abcd

Python client example:

import requests
r = requests.get("http://localhost:5050/experiment/1234abcd")
print(r.json())

Use Cases

Augmenting chat assistants: Provide an LLM with full experiment context (config, metrics, artifacts) so it can answer questions like “Which run had the highest validation F1 and what hyperparameters did it use?”
Automated reporting: Generate summaries of recent runs, include metric charts and top artifacts for weekly model reports without embedding ClearML SDK logic.
Debugging and triage: Quickly compare failing runs to a baseline to identify config changes, dataset diffs, or environment shifts.
CI and gating: Integrate MCP endpoints into CI pipelines to require minimum metric thresholds before promoting a model artifact.
Observability for experiments: Stream live metrics/logs of active experiments into a custom dashboard or chatbot for on-the-fly monitoring.

Notes for Developers

The server is meant to be a thin layer over ClearML. Keep production credentials secure and scope access appropriately (e.g., service account tokens).
Use pagination and filters on /experiments and /search to avoid large payloads when listing many runs.
If you plan to embed this service into LLM agents, sanitize and limit artifact content sizes before returning them to downstream agents.
Check the repository for client examples, recommended schemas, and integration tests to learn idiomatic usage patterns.

For more details, source code, and issues, see the project repository: https://github.com/prassanna-ravishankar/clearml-mcp

ClearML MCP Server: ML Experiment Context and Analysis