Skip to content

Claude Desktop Integration

This guide covers how to integrate BioMCP with Claude Desktop, enabling AI-powered biomedical research directly in your Claude conversations.

Prerequisites

  • Claude Desktop application
  • One of the following:
  • Option A: Python 3.10+ and uv (recommended)
  • Option B: Docker

Installation Methods

This method is fastest and easiest for most users.

1. Install uv

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

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

2. Configure Claude Desktop

Add BioMCP to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "biomcp": {
      "command": "uv",
      "args": ["run", "--with", "biomcp-python", "biomcp", "run"],
      "env": {
        "NCI_API_KEY": "your-nci-api-key-here",
        "ALPHAGENOME_API_KEY": "your-alphagenome-key-here",
        "CBIO_TOKEN": "your-cbioportal-token-here"
      }
    }
  }
}

Option B: Using Docker

This method provides better isolation and consistency across systems.

1. Create a Dockerfile

Create a file named Dockerfile:

FROM python:3.11-slim

# Install BioMCP
RUN pip install biomcp-python

# Set the entrypoint
ENTRYPOINT ["biomcp", "run"]

2. Build the Docker Image

docker build -t biomcp:latest .

3. Configure Claude Desktop

Add BioMCP to your configuration file:

{
  "mcpServers": {
    "biomcp": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "biomcp:latest"],
      "env": {
        "NCI_API_KEY": "your-nci-api-key-here",
        "ALPHAGENOME_API_KEY": "your-alphagenome-key-here",
        "CBIO_TOKEN": "your-cbioportal-token-here"
      }
    }
  }
}

Verification

  1. Restart Claude Desktop after updating the configuration
  2. Start a new conversation
  3. Look for the 🔌 icon indicating MCP is connected
  4. Test with: "Can you search for articles about BRAF mutations in melanoma?"

Setting Up API Keys

While BioMCP works without API keys, some features require them for full functionality:

NCI API Key (Optional)

Enables access to NCI's clinical trials database with advanced filters:

  • Get your key from NCI API Portal
  • Add to configuration as NCI_API_KEY

AlphaGenome API Key (Optional)

Enables variant effect predictions using Google DeepMind's AlphaGenome:

cBioPortal Token (Optional)

Enables enhanced cancer genomics queries:

  • Get token from cBioPortal
  • Add to configuration as CBIO_TOKEN

Usage Examples

Once configured, you can ask Claude to perform various biomedical research tasks:

"Find recent articles about CAR-T therapy for B-cell lymphomas"

Clinical Trials

"Search for actively recruiting trials for EGFR-mutant lung cancer"

Variant Analysis

"What is known about the pathogenicity of BRCA1 c.5266dupC?"

Drug Information

"Tell me about the mechanism of action and indications for pembrolizumab"

Complex Research

"I need a comprehensive analysis of treatment options for a patient with
BRAF V600E melanoma who has progressed on dabrafenib/trametinib"

The Deep Researcher Persona

BioMCP includes a specialized "Deep Researcher" persona that enhances Claude's biomedical research capabilities:

  • Sequential Thinking: Automatically uses the think tool for systematic analysis
  • Comprehensive Coverage: Searches multiple databases and synthesizes findings
  • Evidence-Based: Provides citations and links to primary sources
  • Clinical Focus: Understands medical context and terminology

To activate, simply ask biomedical questions naturally. The persona automatically engages for research tasks.

Troubleshooting

"MCP Connection Failed"

  1. Verify the configuration file path is correct
  2. Check JSON syntax (no trailing commas)
  3. Ensure Claude Desktop has been restarted
  4. Check that uv or Docker is properly installed

"Command Not Found"

For uv:

# Verify uv installation
uv --version

# Ensure PATH includes uv
echo $PATH | grep -q "\.local/bin" || echo "PATH needs updating"

For Docker:

# Verify Docker is running
docker ps

# Test BioMCP container
docker run -it --rm biomcp:latest --help

"No Results Found"

  • Check your internet connection
  • Verify API keys are correctly set (if using optional features)
  • Try simpler queries first
  • Use official gene symbols (e.g., "TP53" not "p53")

Performance Issues

For uv:

  • First run may be slow due to package downloads
  • Subsequent runs use cached environments

For Docker:

  • Ensure Docker has sufficient memory allocated
  • Consider building with --platform flag for Apple Silicon

Advanced Configuration

Custom Environment Variables

Add any additional environment variables your research requires:

{
  "mcpServers": {
    "biomcp": {
      "command": "uv",
      "args": ["run", "--with", "biomcp-python", "biomcp", "run"],
      "env": {
        "BIOMCP_LOG_LEVEL": "DEBUG",
        "BIOMCP_CACHE_DIR": "/path/to/cache",
        "HTTP_PROXY": "http://your-proxy:8080"
      }
    }
  }
}

Multiple Configurations

You can run multiple BioMCP instances with different settings:

{
  "mcpServers": {
    "biomcp-prod": {
      "command": "uv",
      "args": ["run", "--with", "biomcp-python", "biomcp", "run"],
      "env": {
        "BIOMCP_ENV": "production"
      }
    },
    "biomcp-dev": {
      "command": "uv",
      "args": ["run", "--with", "biomcp-python@latest", "biomcp", "run"],
      "env": {
        "BIOMCP_ENV": "development",
        "BIOMCP_LOG_LEVEL": "DEBUG"
      }
    }
  }
}

Best Practices

  1. Start Simple: Test with basic queries before complex research tasks
  2. Be Specific: Use official gene symbols and disease names
  3. Iterate: Refine queries based on initial results
  4. Verify Sources: Always check the provided citations
  5. Save Important Findings: Export conversation or copy key results

Getting Help

Next Steps

Now that BioMCP is integrated with Claude Desktop:

  1. Try the example queries above
  2. Explore How-to Guides for specific research workflows
  3. Learn about Sequential Thinking for complex analyses
  4. Set up additional API keys for enhanced features