Troubleshooting Guide¶

This guide helps you resolve common issues with BioMCP installation, configuration, and usage.

Installation Issues¶

Prerequisites Not Met¶

macOS:

# Install uv (recommended)
brew install uv

# Or using the official installer
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install Node.js for npx (if needed)
brew install node

Linux:

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install Node.js
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

Windows:

# Install uv
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Install Node.js from https://nodejs.org

"Command not found" Error¶

After installing BioMCP, if you get "command not found":

Restart your terminal - PATH updates require a new session
Check installation location:

# For uv tool install
ls ~/.local/bin/biomcp

# For pip install
which biomcp

Add to PATH manually:

# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.local/bin:$PATH"

Reinstall with force:

uv tool install biomcp --force

Use full path:
```
~/.local/bin/biomcp --version
```

Python Version Issues¶

BioMCP requires Python 3.10 or higher:

# Check Python version
python --version

# If too old, install newer version
# macOS
brew install [email protected]

# Linux
sudo apt update
sudo apt install python3.11

# Use pyenv for version management
pyenv install 3.11.8
pyenv local 3.11.8

Configuration Issues¶

API Key Not Working¶

Environment Variable Not Set:

# Check if set
echo $NCI_API_KEY

# Set temporarily
export NCI_API_KEY="your-key-here"

# Set permanently in ~/.bashrc or ~/.zshrc
echo 'export NCI_API_KEY="your-key-here"' >> ~/.bashrc
source ~/.bashrc

Wrong API Key Format:

NCI keys: Should be 36 characters (UUID format)
AlphaGenome: Alphanumeric string
cBioPortal: JWT token format

API Key Permissions:

# Test NCI API key
biomcp health check --verbose

# Test specific API
curl -H "X-API-KEY: $NCI_API_KEY" \
  "https://cts.nlm.nih.gov/api/v2/trials?size=1"

SSL Certificate Errors¶

Update certificates:

# Python certificates
pip install --upgrade certifi

# System certificates (macOS)
brew install ca-certificates

# System certificates (Linux)
sudo apt-get update
sudo apt-get install ca-certificates

Corporate proxy issues:

# Set proxy environment variables
export HTTP_PROXY="http://proxy.company.com:8080"
export HTTPS_PROXY="http://proxy.company.com:8080"
export NO_PROXY="localhost,127.0.0.1"

# Configure pip for proxy
pip config set global.proxy http://proxy.company.com:8080

Search Issues¶

No Results Found¶

1. Check gene symbol:

# Wrong: common names
biomcp article search --gene HER2  # ❌

# Correct: official HGNC symbol
biomcp article search --gene ERBB2  # ✅

# Find correct symbol
biomcp gene get HER2  # Will suggest ERBB2

2. Too restrictive filters:

# Too specific - may return nothing
biomcp article search --gene BRAF --disease "stage IV melanoma" \
  --chemical "dabrafenib and trametinib combination"

# Better - broader search
biomcp article search --gene BRAF --disease melanoma \
  --keyword "dabrafenib trametinib"

3. Check data availability:

# Test if gene exists in database
biomcp gene get YOUR_GENE

# Test if disease term is recognized
biomcp disease get "your disease term"

Location Search Not Working¶

Location searches require coordinates:

# Wrong - city name only
biomcp trial search --condition cancer --city "New York"  # ❌

# Correct - with coordinates
biomcp trial search --condition cancer \
  --latitude 40.7128 --longitude -74.0060 --distance 50  # ✅

Common coordinates:

New York: 40.7128, -74.0060
Los Angeles: 34.0522, -118.2437
Chicago: 41.8781, -87.6298
Houston: 29.7604, -95.3698
Boston: 42.3601, -71.0589

Preprint Search Issues¶

Preprints not appearing:

# Check if preprints are being excluded
biomcp article search --gene BRAF --no-preprints  # Excludes preprints

# Include preprints (default)
biomcp article search --gene BRAF  # Includes preprints

DOI not found:

# Ensure correct DOI format
biomcp article get "10.1101/2024.01.20.23288905"  # bioRxiv format

# Not all preprints are indexed immediately
# Try searching by title/keywords instead

Performance Issues¶

Slow Searches¶

1. Reduce result count:

# Default may be too high
biomcp article search --gene TP53 --limit 100  # Slow

# Reduce for faster results
biomcp article search --gene TP53 --limit 10   # Fast

2. Use specific filters:

# Broad search - slow
biomcp trial search --condition cancer

# Specific search - faster
biomcp trial search --condition "melanoma" --phase PHASE3 \
  --status RECRUITING --country "United States"

3. Check API health:

# See which APIs are slow
biomcp health check --verbose

# Check specific API
biomcp health check --apis-only

Timeout Errors¶

Increase timeout for slow networks:

# Set environment variable
export BIOMCP_TIMEOUT=300  # 5 minutes

# Or use configuration file
echo "timeout: 300" > ~/.biomcp/config.yml

For specific operations:

# In Python scripts
import asyncio
asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())

Memory Issues¶

Large result sets:

# Process in batches
for i in {1..10}; do
  biomcp article search --gene BRCA1 --page $i --limit 100
done

# Use streaming where available
biomcp article search --gene TP53 --format jsonl | \
  while read line; do
    echo "$line" | jq '.pmid'
  done

MCP Server Issues¶

Testing Server Connectivity¶

1. Test with MCP Inspector:

npx @modelcontextprotocol/inspector uv run --with biomcp-python biomcp run

Open http://127.0.0.1:6274 and verify:

Tools list loads
Can invoke a simple tool like gene_getter

2. Test with curl (HTTP mode):

# Start server in HTTP mode
biomcp run --mode http --port 8000

# Test health endpoint
curl http://localhost:8000/health

# Test MCP endpoint
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"method": "tools/list"}'

Claude Desktop Integration Issues¶

Server not appearing:

Check configuration file location:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Validate JSON syntax:

# macOS
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | jq .

Check server starts correctly:

# Test the exact command from config
uv run --with biomcp-python biomcp run

Server crashes: Check logs:

# Enable debug logging
export BIOMCP_LOG_LEVEL=DEBUG
uv run --with biomcp-python biomcp run

Common fixes:

Update to latest version: uv tool install biomcp --force
Clear cache: rm -rf ~/.biomcp/cache
Check port conflicts: lsof -i :8000

Data Quality Issues¶

Outdated Results¶

Check data freshness:

# See when databases were last updated
biomcp health check --verbose | grep "Last updated"

Clear cache if needed:

# Remove cached results
rm -rf ~/.biomcp/cache

# Or set cache TTL
export BIOMCP_CACHE_TTL=900  # 15 minutes

Missing Annotations¶

PubTator3 annotations missing:

Some newer articles may not be fully annotated yet
Try searching by PMID directly
Check if article is indexed: search by title

Variant annotations incomplete:

Not all variants have all annotation types
Rare variants may lack population frequencies
Novel variants won't have ClinVar data

Error Messages¶

Common Error Codes¶

HTTP 429 - Rate Limit Exceeded:

# Add delay between requests
biomcp article search --gene BRAF --delay 1000  # 1 second

# Or reduce parallel requests
export BIOMCP_MAX_CONCURRENT=2

HTTP 404 - Not Found:

Check identifier format (PMID, NCT ID, etc.)
Verify record exists in source database
Try alternative identifiers

HTTP 500 - Server Error:

External API may be down
Check status: biomcp health check
Try again later

Debugging¶

Enable verbose logging:

# Set log level
export BIOMCP_LOG_LEVEL=DEBUG

# Run with verbose output
biomcp article search --gene BRAF --verbose

# Check log files
tail -f ~/.biomcp/logs/biomcp.log

Report bugs: Include when reporting issues:

BioMCP version: biomcp --version
Full error message and stack trace
Command that caused the error
Operating system and Python version
Relevant environment variables

Report at: https://github.com/genomoncology/biomcp/issues

Getting Help¶

Quick Checks¶

Check FAQ first: Frequently Asked Questions
Search existing issues: GitHub Issues
Check examples: How-to Guides

Community Support¶

Issue Tracker: Report bugs, request features
Documentation: PRs welcome for improvements

Professional Support¶

For commercial support, contact: [email protected]

Still having issues? Open a GitHub issue with details.