MutCompute MCP

Protein mutation effect prediction using MutCompute neural networks via Docker

An MCP (Model Context Protocol) server for protein mutation analysis with 12 tools:

• analyze_mutation_hotspots -- Identify critical and flexible protein regions
• calculate_mutation_llh -- Calculate log-likelihood scores for mutations
• validate_pdb_file -- Validate PDB file compatibility
• submit_mutation_prediction -- Predict mutation effects from PDB structures
• submit_batch_mutation_prediction -- Batch processing of multiple PDB files
• submit_mutcompute_pipeline -- Run the full MutCompute analysis pipeline
• get_job_status / get_job_result / get_job_log / cancel_job / list_jobs -- Job management
• list_example_data -- List available example files

Quick Start with Docker

Approach 1: Pull Pre-built Image from GitHub

The fastest way to get started. A pre-built Docker image is automatically published to GitHub Container Registry on every release.

# Pull the latest image
docker pull ghcr.io/macromnex/mutcompute_mcp:latest

# Register with Claude Code (runs as current user to avoid permission issues)
claude mcp add mutcompute_mcp -- docker run -i --rm --user `id -u`:`id -g` -v `pwd`:`pwd` ghcr.io/macromnex/mutcompute_mcp:latest

Note: Run from your project directory. `pwd` expands to the current working directory. The Docker image uses CPU mode by default. To enable GPU, set the THEANO_FLAGS environment variable (see Troubleshooting).

Requirements:

• Docker
• Claude Code installed

That's it! The MutCompute MCP server is now available in Claude Code.

---

Approach 2: Build Docker Image Locally

Build the image yourself and install it into Claude Code. Useful for customization or offline environments.

# Clone the repository
git clone https://github.com/MacromNex/mutcompute_mcp.git
cd mutcompute_mcp

# Build the Docker image
docker build -t mutcompute_mcp:latest .

# Register with Claude Code (runs as current user to avoid permission issues)
claude mcp add mutcompute_mcp -- docker run -i --rm --user `id -u`:`id -g` -v `pwd`:`pwd` mutcompute_mcp:latest

About the Docker Flags:

• -i -- Interactive mode for Claude Code
• --rm -- Automatically remove container after exit
• --user `id -u`:`id -g` -- Runs the container as your current user
• -v -- Mounts your project directory

---

Verify Installation

claude mcp list
# You should see 'mutcompute_mcp' in the output

In Claude Code, you can now use all 12 tools:

• analyze_mutation_hotspots
• calculate_mutation_llh
• validate_pdb_file
• submit_mutation_prediction
• submit_batch_mutation_prediction
• submit_mutcompute_pipeline
• get_job_status, get_job_result, get_job_log, cancel_job, list_jobs
• list_example_data

---

Next Steps

• Detailed documentation: See detail.md for comprehensive guides including local installation, script usage, dual-environment setup, configuration files, and performance benchmarks

---

Usage Examples

Identify Mutation Hotspots

Use analyze_mutation_hotspots on @examples/data/1y4a_BPN_mutcompute.csv to find critical residues in my protein

Predict Mutation Effects

Submit mutation prediction for @examples/data/1y4a_BPN.pdb and check the job status when complete

Validate a PDB File

Use validate_pdb_file to check if @my_protein.pdb is compatible with MutCompute analysis

---

Troubleshooting

Docker Issues

Problem: Container not found or pull fails

# Verify Docker is running
docker info

# Pull with explicit tag
docker pull ghcr.io/macromnex/mutcompute_mcp:latest

Problem: Permission denied on output files

# Ensure you're using the --user flag
docker run -i --rm --user `id -u`:`id -g` -v `pwd`:`pwd` ghcr.io/macromnex/mutcompute_mcp:latest

Problem: Want to use GPU instead of CPU

# Add --gpus all and set THEANO_FLAGS for GPU mode
claude mcp add mutcompute_mcp -- docker run -i --rm --user `id -u`:`id -g` --gpus all -e THEANO_FLAGS="device=cuda,floatX=float32" -v `pwd`:`pwd` ghcr.io/macromnex/mutcompute_mcp:latest

Problem: MCP server not responding

# Re-register with Claude Code
claude mcp remove mutcompute_mcp
claude mcp add mutcompute_mcp -- docker run -i --rm --user `id -u`:`id -g` -v `pwd`:`pwd` ghcr.io/macromnex/mutcompute_mcp:latest

Problem: File paths not found inside container

# Make sure to run Claude Code from the directory containing your files
# The -v `pwd`:`pwd` flag mounts only the current directory
cd /path/to/your/project
claude

---

License

Based on the MutCompute neural network ensemble for protein mutation effect prediction.

Credits

Based on MutCompute -- Neural network ensemble for protein mutation analysis.