Cooler MCP Server

A Model Context Protocol (MCP) server that exposes Cooler (open2c/cooler — Hi-C contact matrix toolkit) for use with Claude or any MCP-compatible client.

Tools

Background execution: Long-running operations (cooler_dump, cooler_balance, cooler_zoomify, cooler_merge, cooler_cload, cooler_coarsen) run in the background and return a job_id immediately — no timeout risk for large files. Call check_job_status(job_id) to poll until the job is "completed" or "failed".

cooler_info, cooler_ls, cooler_makebins, and cooler_report run synchronously and return results directly.

Requirements

• Python 3.13+
• uv
• macOS / Linux: pip install cooler
• Windows: WSL — run wsl --install in PowerShell as Administrator, then restart your computer

Local Setup

1. Clone the repository

git clone https://github.com/JesKwek/cooler-mcp.git
cd cooler-mcp

2. Add to Claude Desktop

Open your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the following — replace the path with the actual location where you cloned the repo:

{
  "mcpServers": {
    "cooler-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/cooler-mcp",
        "main.py"
      ]
    }
  }
}

Save the file and restart Claude Desktop. The cooler tools will be available in your next conversation.

Usage Examples

1. Check if cooler is installed

"Is cooler installed on my system?"

{
  "installed": true,
  "path": "/usr/local/bin/cooler",
  "version": "cooler, version 0.10.2",
  "via_wsl": false,
  "error": null
}

{
  "installed": false,
  "path": null,
  "version": null,
  "via_wsl": false,
  "error": null
}

2. Install cooler on macOS or Linux

"Install cooler on my Mac."

"Install cooler on my Linux machine."

Claude will use pip to install the cooler package into the current Python environment.

{
  "success": true,
  "message": "Cooler installed successfully. Binary at: /usr/local/bin/cooler",
  "version": "Successfully installed cooler-0.10.2",
  "error": null
}

3. Install cooler on Windows

"Install cooler on Windows."

Cooler is installed on Windows through WSL (Windows Subsystem for Linux). If WSL is not yet set up, Claude returns step-by-step instructions.

{
  "success": false,
  "message": "WSL (Windows Subsystem for Linux) is not installed.\n\nTo install WSL:\n1. Open PowerShell or Command Prompt as Administrator\n2. Run: wsl --install\n3. Restart your computer when prompted\n4. After restart, WSL will finish setting up...",
  "error": "WSL not installed"
}

{
  "success": true,
  "message": "Cooler installed successfully inside WSL via pip.",
  "error": null
}

4. Inspect a .cool or .mcool file

"Show me the metadata for /data/contacts.cool"

"What resolutions are available in /data/contacts.mcool?"

{
  "success": true,
  "output": "{\n  \"bin-size\": 10000,\n  \"bin-type\": \"fixed\",\n  \"genome-assembly\": \"hg38\",\n  \"nchroms\": 25,\n  \"nbins\": 318535,\n  \"nnz\": 48291034\n}",
  "error": null
}

{
  "success": true,
  "uris": [
    "/resolutions/1000",
    "/resolutions/5000",
    "/resolutions/10000",
    "/resolutions/25000"
  ],
  "output": "/resolutions/1000\n/resolutions/5000\n/resolutions/10000\n/resolutions/25000",
  "error": null
}

5. Create a .cool file from pairs (background)

"Create a cooler from /data/sample.pairs.gz using bins at 10 kb resolution with hg38 chromsizes."

{
  "job_id": "a3f8b201",
  "pid": 61200,
  "status": "running",
  "message": "cload (pairix) started in the background. Call check_job_status('a3f8b201') to monitor progress.",
  "output_cool": "/data/sample.10kb.cool",
  "format": "pairix",
  "error": null
}

6. Generate a multi-resolution .mcool file (background)

"Zoomify /data/sample.10kb.cool into an .mcool with resolutions 1000, 5000, 10000, 25000."

{
  "job_id": "d92c4e77",
  "pid": 61400,
  "status": "running",
  "message": "Zoomify started in the background. Call check_job_status('d92c4e77') to monitor progress.",
  "output_path": "/data/sample.mcool",
  "error": null
}

{
  "job_id": "d92c4e77",
  "status": "completed",
  "pid": 61400,
  "operation": "cooler_zoomify",
  "started_at": "2024-06-01T12:00:00",
  "stderr": null,
  "error": null
}

7. Run matrix balancing (background)

"Balance /data/sample.10kb.cool using 4 processes."

{
  "job_id": "f1b9a034",
  "pid": 61550,
  "status": "running",
  "message": "Balancing started in the background. Call check_job_status('f1b9a034') to monitor progress.",
  "cool_uri": "/data/sample.10kb.cool",
  "error": null
}

8. Dump pixels to TSV (background)

"Dump all cis pixels from /data/sample.10kb.cool to /data/pixels.tsv"

"Extract chr1 contacts from /data/sample.mcool::10000 into /data/chr1.tsv"

{
  "job_id": "b4e70c11",
  "pid": 61700,
  "status": "running",
  "message": "Dump started in the background. Call check_job_status('b4e70c11') to monitor progress.",
  "output_path": "/data/pixels.tsv",
  "error": null
}

9. Generate a Hi-C QC HTML report

"Generate a QC report for /data/sample.mcool::10000 and save it to /data/report.html"

Produces a self-contained HTML file with summary metrics, cis/trans breakdown, distance decay curve, per-chromosome contact density, and an interactive contact matrix heatmap for a representative chromosome.

{
  "success": true,
  "output_html": "/data/report.html",
  "sample": "sample",
  "genome": "hg38",
  "resolution": 10000,
  "total_contacts": 482910340,
  "cis_ratio": 0.8312,
  "qc_summary": "Excellent library quality (cis ratio ≥80%): 83.1%\nDistance decay shows expected power-law behaviour.\nNo chromosomes with unusually high or low contact density detected.",
  "error": null
}

10. List all background jobs

"Show me all cooler jobs running right now."

{
  "jobs": [
    {
      "job_id": "d92c4e77",
      "status": "running",
      "operation": "cooler_zoomify",
      "pid": 61400,
      "started_at": "2024-06-01T12:05:00",
      "cool_uri": "/data/sample.10kb.cool",
      "output_path": "/data/sample.mcool"
    },
    {
      "job_id": "a3f8b201",
      "status": "completed",
      "operation": "cooler_cload",
      "pid": 61200,
      "started_at": "2024-06-01T12:00:00",
      "cool_uri": null,
      "output_path": "/data/sample.10kb.cool"
    }
  ],
  "total": 2
}

Background Job Workflow

cooler_dump / cooler_balance / cooler_zoomify /
cooler_merge / cooler_cload / cooler_coarsen
        │
        ▼
   returns job_id   ←── no timeout risk
        │
        ▼
check_job_status(job_id)
        │
   status = "running"?  ──► poll again later
        │
   status = "completed"  ──► output file is ready
   status = "failed"     ──► check stderr field

cooler_info / cooler_ls / cooler_makebins / cooler_report
        │
        ▼
   returns result inline  ←── synchronous, typically fast

Note: The job registry is in-memory. Jobs are lost if the MCP server process restarts. Always call check_job_status in the same session that launched the job.

cooler_cload Parameters

cooler_zoomify Parameters

Platform Support