SPIRED-Stab MCP

Protein stability prediction using SPIRED-Stab deep learning model via Docker

An MCP (Model Context Protocol) server for protein stability prediction with 6 core tools:

• Predict stability changes (ΔΔG and ΔTm) for protein variants from CSV or FASTA

• Analyze single variant mutations against a wild-type reference

• Submit large batch stability prediction jobs with async tracking

• Submit systematic batch mutation analysis

• Monitor and retrieve prediction results

• List available example datasets

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/spired_stab_mcp:latest

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

Note: Run from your project directory. `pwd` expands to the current working directory.

Requirements:

• Docker with GPU support (nvidia-docker or Docker with NVIDIA runtime)

• Claude Code installed

That's it! The SPIRED-Stab 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/spired_stab_mcp.git
cd spired_stab_mcp

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

# Register with Claude Code (runs as current user to avoid permission issues)
claude mcp add spired_stab -- docker run -i --rm --user `id -u`:`id -g` --gpus all --ipc=host -v `pwd`:`pwd` spired_stab_mcp:latest

Note: Run from your project directory. `pwd` expands to the current working directory.

Requirements:

• Docker with GPU support

• Claude Code installed

• Git (to clone the repository)

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, so output files are owned by you (not root)

• --gpus all — Grants access to all available GPUs

• --ipc=host — Uses host IPC namespace for PyTorch shared memory

• -v — Mounts your project directory so the container can access your data

Verify Installation

After adding the MCP server, you can verify it's working:

# List registered MCP servers
claude mcp list

# You should see 'spired_stab' in the output

In Claude Code, you can now use all 6 SPIRED-Stab tools:

• predict_stability

• analyze_single_variant

• submit_stability_prediction

• submit_batch_mutation_analysis

• get_job_status

• get_job_result

Next Steps

• Detailed documentation: See detail.md for comprehensive guides on:

  • Available MCP tools and parameters

  • Local Python environment setup (alternative to Docker)

  • Example workflows and use cases

  • Data format requirements

  • Troubleshooting

Usage Examples

Once registered, you can use the SPIRED-Stab tools directly in Claude Code. Here are some common workflows:

Example 1: Quick Stability Prediction

I have protein variants at /path/to/variants.csv with a 'seq' column and wild-type sequence at /path/to/wt.fasta. Can you use predict_stability to predict stability changes for all variants and save results to /path/to/results.csv?

Example 2: Single Variant Analysis

I want to analyze the effect of mutation I31L on my protein. The wild-type sequence is at /path/to/wt.fasta. Can you use analyze_single_variant to predict the stability change for this mutation?

Example 3: Systematic Mutation Scanning

I want to explore all possible mutations at positions 31, 67, and 124 of my protein at /path/to/wt.fasta. Can you submit a batch mutation analysis job using submit_batch_mutation_analysis with max 100 variants, and monitor progress until completion?

Troubleshooting

Docker not found?

docker --version  # Install Docker if missing

GPU not accessible?

• Ensure NVIDIA Docker runtime is installed

• Check with: docker run --gpus all ubuntu nvidia-smi

Claude Code not found?

# Install Claude Code
npm install -g @anthropic-ai/claude-code

Out of GPU memory?

• SPIRED-Stab requires 4-6 GB VRAM

• Use device: "cpu" for CPU inference (significantly slower)

• For very large datasets, use submit_stability_prediction for background processing

License

Research use — Based on SPIRED-Stab by YoGo-1030.