<!--
# COPYRIGHT NOTICE
# This file is part of the "Universal Biomedical Skills" project.
# Copyright (c) 2026 MD BABU MIA, PhD <md.babu.mia@mssm.edu>
# All Rights Reserved.
#
# This code is proprietary and confidential.
# Unauthorized copying of this file, via any medium is strictly prohibited.
#
# Provenance: Authenticated by MD BABU MIA

-->

# Desktop Integration

This guide covers how to integrate BioMCP with desktop applications that support the Model Context Protocol (MCP), such as Claude Desktop, enabling AI-powered biomedical research directly in your conversations.

## Prerequisites

- An MCP-compatible desktop application (e.g., [Claude Desktop](https://claude.ai/download))
- One of the following:
  - **Option A**: Python 3.10+ and [uv](https://docs.astral.sh/uv/) (recommended)
  - **Option B**: [Docker](https://www.docker.com/products/docker-desktop/)

## Installation Methods

### Option A: Using uv (Recommended)

This method is fastest and easiest for most users.

#### 1. Install uv

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

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

#### 2. Configure Your Desktop Application

Add BioMCP to your application's configuration file (e.g., `claude_desktop_config.json` for Claude Desktop).

**Location (Claude Desktop):**
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```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`:

```dockerfile
FROM python:3.11-slim

# Install BioMCP
RUN pip install biomcp-python

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

#### 2. Build the Docker Image

```bash
docker build -t biomcp:latest .
```

#### 3. Configure Your Desktop Application

Add BioMCP to your configuration file:

```json
{
  "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 your desktop application after updating the configuration
2. Start a new conversation
3. Look for the indicator that MCP is connected (e.g., a plug icon)
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](https://api.cancer.gov)
- Add to configuration as `NCI_API_KEY`

### AlphaGenome API Key (Optional)

Enables variant effect predictions using Google DeepMind's AlphaGenome:

- Register at [AlphaGenome Portal](https://alphagenome.google.com)
- Add to configuration as `ALPHAGENOME_API_KEY`

### cBioPortal Token (Optional)

Enables enhanced cancer genomics queries:

- Get token from [cBioPortal](https://www.cbioportal.org/webAPI)
- Add to configuration as `CBIO_TOKEN`

## Usage Examples

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

### Literature Search

```
"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 enables advanced research capabilities:

- **Sequential Thinking**: Automatically uses tools 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.

## Troubleshooting

### "MCP Connection Failed"

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

### "Command Not Found"

**For uv**:

```bash
# Verify uv installation
uv --version

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

**For Docker**:

```bash
# 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:

```json
{
  "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:

```json
{
  "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

- **Documentation**: [BioMCP Docs](https://github.com/genomoncology/biomcp)
- **Issues**: [GitHub Issues](https://github.com/genomoncology/biomcp/issues)
- **Community**: [Discussions](https://github.com/genomoncology/biomcp/discussions)

## Next Steps

Now that BioMCP is integrated with your desktop application:

1. Try the [example queries](#usage-examples) above
2. Explore [How-to Guides](../how-to-guides/01-find-articles-and-cbioportal-data.md) for specific research workflows
3. Learn about [Sequential Thinking](../concepts/03-sequential-thinking-with-the-think-tool.md) for complex analyses
4. Set up [additional API keys](03-authentication-and-api-keys.md) for enhanced features

<!-- AUTHOR_SIGNATURE: 9a7f3c2e-MD-BABU-MIA-2026-MSSM-SECURE -->