Bio-MCP BLAST

🔍MCP server for NCBI BLAST sequence similarity search

Enable AI assistants to perform BLAST searches through natural language. Search nucleotide and protein databases, create custom databases, and get formatted results instantly.

- blastn- Nucleotide-nucleotide BLAST search
- blastp- Protein-protein BLAST search
- makeblastdb- Create custom BLAST databases
- Multiple output formats- JSON, XML, tabular, pairwise
- Flexible input- File paths or raw sequences
- Queue support- Async processing for large searches

# Install BLAST+ conda install -c bioconda blast # Or via package manager # macOS: brew install blast # Ubuntu: sudo apt-get install ncbi-blast+ # Install MCP server git clone https://github.com/bio-mcp/bio-mcp-blast.git cd bio-mcp-blast pip install -e .

# Start the server python -m src.server # Or with queue support python -m src.main --mode queue

{ "mcpServers": { "bio-blast": { "command": "python", "args": ["-m", "src.server"], "cwd": "/path/to/bio-mcp-blast" } } }

User: "BLAST this sequence against nr: ATGCGATCGATCG" AI: [calls blastn] → Returns top hits with E-values and alignments

User: "Search proteins.fasta against SwissProt database" AI: [calls blastp] → Processes file and returns similarity results

User: "Create a BLAST database from reference_genomes.fasta" AI: [calls makeblastdb] → Creates searchable database files

User: "BLAST large_dataset.fasta against nt database" AI: [calls blastn_async] → "Job submitted! ID: abc123, checking progress..."

- query(required) - Path to FASTA file or sequence string
- database(required) - Database name (e.g., "nt", "nr") or path
- evalue- E-value threshold (default: 10)
- max_hits- Maximum hits to return (default: 50)
- output_format- Output format: "tabular", "xml", "json", "pairwise"

- Same as blastn, but for protein sequences

- input_file(required) - Path to FASTA file
- database_name(required) - Name for output database
- dbtype(required) - "nucl" or "prot"
- title- Database title (optional)

- blastn_async- Submit nucleotide search to queue
- blastp_async- Submit protein search to queue
- get_job_status- Check job progress
- get_job_result- Retrieve completed results

# Basic settings export BIO_MCP_MAX_FILE_SIZE=100000000 # 100MB max file size export BIO_MCP_TIMEOUT=300 # 5 minute timeout export BIO_MCP_BLAST_PATH="blastn" # BLAST executable path # Queue mode settings export BIO_MCP_QUEUE_URL="http://localhost:8000"

# Download common databases mkdir -p ~/blast-databases cd ~/blast-databases # NCBI databases (large downloads!) update_blastdb.pl --decompress nt update_blastdb.pl --decompress nr update_blastdb.pl --decompress swissprot # Set environment variable export BLASTDB=~/blast-databases

# Build image docker build -t bio-mcp-blast . # Run container docker run -p 5000:5000 \ -v ~/blast-databases:/data/blast-db:ro \ -e BLASTDB=/data/blast-db \ bio-mcp-blast

services: blast-server: build: . ports: - "5000:5000" volumes: - ./databases:/data/blast-db:ro environment: - BLASTDB=/data/blast-db - BIO_MCP_TIMEOUT=600

For long-running BLAST searches, use the queue system:

# Start queue infrastructure cd ../bio-mcp-queue ./setup-local.sh # Start BLAST server with queue support python -m src.main --mode queue --queue-url http://localhost:8000

# Submit async job job_info = await blast_server.submit_job( job_type="blastn", parameters={ "query": "large_sequences.fasta", "database": "nt", "evalue": 0.001 } ) # Check status status = await blast_server.get_job_status(job_info["job_id"]) # Get results when complete results = await blast_server.get_job_result(job_info["job_id"])

# Fields: query_id, subject_id, percent_identity, alignment_length, ... Query_1 gi|123456 98.5 500 7 0 1 500 1000 1499 1e-180 633

{ "BlastOutput2": [{ "report": { "results": { "search": { "query_title": "Query_1", "hits": [...] } } } }] }

Standard BLAST XML format for programmatic parsing.

# Run tests pytest tests/ -v # Test with real data python tests/test_integration.py # Performance testing python tests/benchmark.py

- Use SSD storage for databases
- Increase available RAM
- Use multiple CPU cores:export BLAST_NUM_THREADS=8

- Use smaller, specific databases when possible
- Consider pre-filtering sequences
- Use appropriate E-value thresholds

- Scale workers based on CPU cores
- Use separate queues for different database sizes
- Monitor memory usage with large databases

- File size limits prevent resource exhaustion
- Path validation prevents directory traversal
- Command injection protection

- Containers run as non-root user
- Temporary files isolated per job
- Network access restricted in production

# Check installation which blastn blastn -version # Install via conda conda install -c bioconda blast

# Check BLASTDB environment variable echo $BLASTDB # List available databases blastdbcmd -list /path/to/databases

# Reduce max_target_seqs blastn -max_target_seqs 100 # Use streaming for large outputs # Increase system swap space

# Increase timeout export BIO_MCP_TIMEOUT=3600 # 1 hour # Or use queue mode for long searches python -m src.main --mode queue

- BLAST Documentation
- BLAST Databases
- Bio-MCP Examples
- Queue System Setup
- Fork the repository
- Create a feature branch
- Add tests for new functionality
- Ensure all tests pass
- Submit a pull request

SeeCONTRIBUTING.mdfor detailed guidelines.

- 🐛Bug Reports:GitHub Issues
- 💡Feature Requests:GitHub Issues
- 📖Documentation:Bio-MCP Docs
- 💬Discussions:GitHub Discussions

Search the web using Kagi's search API