Samtools MCP Server

A Model Context Protocol (MCP) server that exposes samtools (SAM/BAM/CRAM processing toolkit) for use with Claude or any MCP-compatible client.

Tools

Background execution: samtools_view with an output_path runs in the background and returns a job_id immediately — no timeout risk for large BAM/CRAM conversions. Call check_job_status(job_id) to poll until the job is "completed" or "failed".

samtools_view without an output_path (text inspection or record counting) runs synchronously and returns the result directly.

Requirements

• Python 3.13+
• uv
• macOS: Homebrew — brew install samtools
• Linux: sudo apt-get install samtools
• 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/samtools-mcp.git
cd samtools-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": {
    "samtools-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/samtools-mcp",
        "main.py"
      ]
    }
  }
}

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

Usage Examples

1. Check if samtools is installed

"Is samtools installed on my system?"

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

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

2. Install samtools on macOS or Linux

"Install samtools on my Mac."

"Install samtools on my Linux machine."

Claude will use Homebrew on macOS or apt-get on Linux. If neither is available, it will suggest alternatives (conda, dnf, zypper).

{
  "success": true,
  "message": "samtools installed successfully via Homebrew.",
  "error": null
}

3. Install samtools on Windows

"Install samtools on Windows."

samtools 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": "samtools installed successfully inside WSL.",
  "error": null
}

4. Convert SAM → BAM (background)

"Convert /data/reads.sam to BAM and save it as /data/reads.bam"

File conversions run in the background. The tool returns a job_id immediately; poll with check_job_status.

{
  "job_id": "c7a21f04",
  "pid": 52100,
  "status": "running",
  "message": "samtools view started in the background. Call check_job_status('c7a21f04') to monitor progress.",
  "output_path": "/data/reads.bam",
  "via_wsl": false,
  "error": null
}

{
  "job_id": "c7a21f04",
  "status": "completed",
  "pid": 52100,
  "operation": "samtools_view",
  "started_at": "2024-06-01T12:00:00",
  "input_path": "/data/reads.sam",
  "output_path": "/data/reads.bam",
  "via_wsl": false,
  "stderr": null,
  "error": null
}

5. Filter reads by region (background)

"Extract all reads aligned to chr1:1000000-2000000 from /data/sorted.bam and save to /data/chr1_region.bam"

"Filter reads with MAPQ ≥ 30 from /data/input.bam and write to /data/hq.bam"

{
  "job_id": "b83de501",
  "pid": 52340,
  "status": "running",
  "message": "samtools view started in the background. Call check_job_status('b83de501') to monitor progress.",
  "output_path": "/data/chr1_region.bam",
  "via_wsl": false,
  "error": null
}

6. Inspect BAM (synchronous — returns text inline)

"Show me the first reads in /data/reads.bam"

When no output_path is given, the query runs synchronously and returns up to 200 lines of text.

{
  "success": true,
  "message": "Returned 42 lines.",
  "output_path": null,
  "text_output": "SRR001234.1\t16\tchr1\t10001\t30\t...\n...",
  "count": null,
  "via_wsl": false,
  "error": null
}

7. Count alignments (synchronous)

"How many reads are in /data/reads.bam?"

{
  "success": true,
  "message": "Record count: 5432198",
  "output_path": null,
  "text_output": "5432198",
  "count": 5432198,
  "via_wsl": false,
  "error": null
}

8. List all background jobs

"Show me all samtools jobs running right now."

{
  "jobs": [
    {
      "job_id": "b83de501",
      "status": "running",
      "operation": "samtools_view",
      "pid": 52340,
      "started_at": "2024-06-01T12:05:00",
      "input_path": "/data/sorted.bam",
      "output_path": "/data/chr1_region.bam",
      "via_wsl": false
    },
    {
      "job_id": "c7a21f04",
      "status": "completed",
      "operation": "samtools_view",
      "pid": 52100,
      "started_at": "2024-06-01T12:00:00",
      "input_path": "/data/reads.sam",
      "output_path": "/data/reads.bam",
      "via_wsl": false
    }
  ],
  "total": 2
}

Background Job Workflow

samtools_view (with output_path)
        │
        ▼
   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

samtools_view (no output_path — text/count)
        │
        ▼
   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.

samtools_view Parameters

Platform Support