# Clearml Mcp

> lightweight MCP server for ClearML

- **Type:** MCP server
- **Install:** `agentstack add mcp-prassanna-ravishankar-clearml-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [prassanna-ravishankar](https://agentstack.voostack.com/s/prassanna-ravishankar)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [prassanna-ravishankar](https://github.com/prassanna-ravishankar)
- **Source:** https://github.com/prassanna-ravishankar/clearml-mcp

## Install

```sh
agentstack add mcp-prassanna-ravishankar-clearml-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# ClearML MCP Server

[](https://badge.fury.io/py/clearml-mcp)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)

A lightweight **Model Context Protocol (MCP) server** that enables AI assistants to interact with [ClearML](https://clear.ml) experiments, models, and projects. Get comprehensive ML experiment context and analysis directly in your AI conversations.

## ✨ Features

- **🔍 Experiment Discovery**: Find and analyze ML experiments across projects
- **📊 Performance Analysis**: Compare model metrics and training progress
- **📈 Real-time Metrics**: Access training scalars, validation curves, and convergence analysis
- **🏷️ Smart Search**: Filter tasks by name, tags, status, and custom queries
- **📦 Artifact Management**: Retrieve model files, datasets, and experiment outputs
- **🌐 Cross-platform**: Works with all major AI assistants and code editors

## 📋 Requirements

- **uv** ([installation guide](https://docs.astral.sh/uv/getting-started/installation/)) for `uvx` command
- **ClearML account** with valid API credentials in `~/.clearml/clearml.conf`

## 🚀 Quick Start

### Prerequisites

You need a configured ClearML environment with your credentials in `~/.clearml/clearml.conf`:

```ini
[api]
api_server = https://api.clear.ml
web_server = https://app.clear.ml
files_server = https://files.clear.ml
credentials {
    "access_key": "your-access-key",
    "secret_key": "your-secret-key"
}
```

Get your credentials from [ClearML Settings](https://app.clear.ml/settings).

### Installation

```bash
# Install from PyPI
pip install clearml-mcp

# Or run directly with uvx (no installation needed)
uvx clearml-mcp
```

## 🔌 Integrations

🤖 Claude Desktop

Add to your Claude Desktop configuration:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "clearml": {
      "command": "uvx",
      "args": ["clearml-mcp"]
    }
  }
}
```

Alternative with pip installation:
```json
{
  "mcpServers": {
    "clearml": {
      "command": "python",
      "args": ["-m", "clearml_mcp.clearml_mcp"]
    }
  }
}
```

⚡ Cursor

Add to your Cursor settings (`Ctrl/Cmd + ,` → Search "MCP"):

```json
{
  "mcp.servers": {
    "clearml": {
      "command": "uvx",
      "args": ["clearml-mcp"]
    }
  }
}
```

Or add to `.cursorrules` in your project:
```
When analyzing ML experiments or asking about model performance, use the clearml MCP server to access experiment data, metrics, and artifacts.
```

🔥 Continue

Add to your Continue configuration (`~/.continue/config.json`):

```json
{
  "mcpServers": {
    "clearml": {
      "command": "uvx",
      "args": ["clearml-mcp"]
    }
  }
}
```

🦾 Cody

Add to your Cody settings:

```json
{
  "cody.experimental.mcp": {
    "servers": {
      "clearml": {
        "command": "uvx",
        "args": ["clearml-mcp"]
      }
    }
  }
}
```

🧠 Other AI Assistants

For any MCP-compatible AI assistant, use this configuration:

```json
{
  "mcpServers": {
    "clearml": {
      "command": "uvx",
      "args": ["clearml-mcp"]
    }
  }
}
```

**Compatible with:**
- Zed Editor
- OpenHands
- Roo-Cline
- Any MCP-enabled application

## 🛠️ Available Tools

The ClearML MCP server provides **14 comprehensive tools** for ML experiment analysis:

### 📊 Task Operations
- `get_task_info` - Get detailed task information, parameters, and status
- `list_tasks` - List tasks with advanced filtering (project, status, tags, user)
- `get_task_parameters` - Retrieve hyperparameters and configuration
- `get_task_metrics` - Access training metrics, scalars, and plots
- `get_task_artifacts` - Get artifacts, model files, and outputs

### 🤖 Model Operations
- `get_model_info` - Get model metadata and configuration details
- `list_models` - Browse available models with filtering
- `get_model_artifacts` - Access model files and download URLs

### 📁 Project Operations
- `list_projects` - Discover available ClearML projects
- `get_project_stats` - Get project statistics and task summaries
- `find_project_by_pattern` - Find projects matching name patterns
- `find_experiment_in_project` - Find specific experiments within projects

### 🔍 Analysis Tools
- `compare_tasks` - Compare multiple tasks by specific metrics
- `search_tasks` - Advanced search by name, tags, comments, and more

## 💡 Usage Examples

### Demo

[](https://asciinema.org/a/9Bf0hiIsEqGbf3zKnkdsNIbf0)

Once configured, you can ask your AI assistant questions like:

- *"Show me the latest experiments in the 'computer-vision' project"*
- *"Compare the accuracy metrics between tasks task-123 and task-456"*
- *"What are the hyperparameters for the best performing model?"*
- *"Find all failed experiments from last week"*
- *"Get the training curves for my latest BERT fine-tuning"*

## 🏗️ Development

### Setup

```bash
# Clone and setup with UV
git clone https://github.com/prassanna-ravishankar/clearml-mcp.git
cd clearml-mcp
uv sync

# Run locally
uv run python -m clearml_mcp.clearml_mcp
```

### Available Commands

```bash
# Run tests with coverage
uv run task coverage

# Lint and format
uv run task lint
uv run task format

# Type checking
uv run task type

# Run examples
uv run task consolidated-debug  # Full ML debugging demo
uv run task example-simple      # Basic integration
uv run task find-experiments    # Discover real experiments
```

### Testing with MCP Inspector

```bash
# Test the MCP server directly
npx @modelcontextprotocol/inspector uvx clearml-mcp
```

## 🚨 Troubleshooting

Connection Issues

**"No ClearML projects accessible"**
- Verify your `~/.clearml/clearml.conf` credentials
- Test with: `python -c "from clearml import Task; print(Task.get_projects())"`
- Check network access to your ClearML server

**Module not found errors**
- Try `bunx clearml-mcp` instead of `uvx clearml-mcp`
- Or use direct Python: `python -m clearml_mcp.clearml_mcp`

Performance Issues

**Large dataset queries**
- Use filters in `list_tasks` to limit results
- Specify `project_name` to narrow scope
- Use `task_status` filters (`completed`, `running`, `failed`)

**Slow metric retrieval**
- Request specific metrics instead of all metrics
- Use `compare_tasks` with metric names for focused analysis

## 🤝 Contributing

Contributions welcome! This project uses:

- **UV** for dependency management
- **Ruff** for linting and formatting
- **Pytest** for testing with 69% coverage
- **GitHub Actions** for CI/CD

See our [testing philosophy](.cursor/rules/testing-philosophy.mdc) and [linting approach](.cursor/rules/linting-philosophy.mdc) for development guidelines.

## 📄 License

MIT License - see [LICENSE](LICENSE) for details.

## 🔗 Links

- **PyPI**: [clearml-mcp](https://pypi.org/project/clearml-mcp/)
- **ClearML**: [clear.ml](https://clear.ml)
- **Model Context Protocol**: [MCP Specification](https://modelcontextprotocol.io/)

---

**Created by [Prass, The Nomadic Coder](https://github.com/prassanna-ravishankar)**

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [prassanna-ravishankar](https://github.com/prassanna-ravishankar)
- **Source:** [prassanna-ravishankar/clearml-mcp](https://github.com/prassanna-ravishankar/clearml-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-prassanna-ravishankar-clearml-mcp
- Seller: https://agentstack.voostack.com/s/prassanna-ravishankar
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.