Samtools MCP server for AI agents

SAMtools MCP (Model Control Protocol) is an implementation providing a standardized interface for working with SAM/BAM/CRAM files. It enables viewing, converting, sorting, and indexing genomic alignment files through a consistent API, allowing you to manipulate and analyze genomic data efficiently.

Installation

Using Docker (Recommended)

The easiest way to use SAMtools MCP is through Docker:

# Pull the Docker image
docker pull nadhir/samtools-mcp:latest

# Run the container
docker run -it --rm nadhir/samtools-mcp:latest

# To process BAM files, mount a volume:
docker run -it --rm -v /path/to/your/bam/files:/data nadhir/samtools-mcp:latest

Local Installation

# Clone the repository
git clone https://github.com/your-username/samtools_mcp.git
cd samtools_mcp

# Install dependencies
pip install uv
uv pip install -r requirements.txt

Configuration

MCP Server Configuration

To configure the MCP server to use the Docker image, add the following to your MCP configuration file:

{
  "servers": {
    "samtools": {
      "type": "docker",
      "image": "nadhir/samtools-mcp:latest",
      "volumes": [
        {
          "source": "/path/to/your/data",
          "target": "/data"
        }
      ]
    }
  }
}

Local MCP Configuration

To configure the MCP to run using uv, add the following to your ~/.cursor/mcp.json:

{
  "samtools_mcp": {
    "command": "uv",
    "args": ["run", "--with", "fastmcp", "fastmcp", "run", "/path/to/samtools_mcp.py"]
  }
}

Replace /path/to/samtools_mcp.py with the actual path to your samtools_mcp.py file.

Usage

Basic Commands

Here are some fundamental operations you can perform:

View BAM file:

from samtools_mcp import SamtoolsMCP

mcp = SamtoolsMCP()
result = mcp.view(input_file="/data/example.bam")

Sort BAM file:

result = mcp.sort(input_file="/data/example.bam", output_file="/data/sorted.bam")

Index BAM file:

result = mcp.index(input_file="/data/sorted.bam")

Advanced Usage

For more specific operations:

View specific region with flags:

result = mcp.view(
    input_file="/data/example.bam",
    region="chr1:1000-2000",
    flags_required="0x2",
    output_format="SAM"
)

Sort by read name:

result = mcp.sort(
    input_file="/data/example.bam",
    output_file="/data/namesorted.bam",
    sort_by_name=True
)

Supported Tools

View and Convert Files

The view command allows you to examine and convert between file formats:

# Convert BAM to SAM
result = mcp.view(
    input_file="/data/example.bam",
    output_format="SAM",
    output_file="/data/output.sam"
)

Sort Alignment Files

Sort your BAM/CRAM files by coordinates or read names:

# Sort with multiple threads
result = mcp.sort(
    input_file="/data/example.bam",
    output_file="/data/sorted.bam",
    threads=4,
    memory_per_thread="1G"
)

Generate Statistics

Get comprehensive statistics about your alignment files:

# Generate flagstat report
result = mcp.flagstat(input_file="/data/example.bam")

# Get index statistics
result = mcp.idxstats(input_file="/data/indexed.bam")

Calculate Read Depth

Analyze coverage depth across regions:

# Calculate depth for specific regions
result = mcp.depth(
    input_file="/data/example.bam",
    regions=["chr1:1000-2000", "chr2:3000-4000"]
)

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "samtools" '{"type":"docker","image":"nadhir/samtools-mcp:latest","volumes":[{"source":"/path/to/your/data","target":"/data"}]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "samtools": {
            "type": "docker",
            "image": "nadhir/samtools-mcp:latest",
            "volumes": [
                {
                    "source": "/path/to/your/data",
                    "target": "/data"
                }
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

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

2. Add this to your configuration file:

{
    "mcpServers": {
        "samtools": {
            "type": "docker",
            "image": "nadhir/samtools-mcp:latest",
            "volumes": [
                {
                    "source": "/path/to/your/data",
                    "target": "/data"
                }
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect