| Name | biomcp-python JSON |
| Version |
0.4.3
JSON |
| download |
| home_page | None |
| Summary | Biomedical Model Context Protocol Server |
| upload_time | 2025-07-08 15:21:51 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | <4.0,>=3.10 |
| license | None |
| keywords |
python
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# BioMCP: Biomedical Model Context Protocol
BioMCP is an open source (MIT License) toolkit that empowers AI assistants and
agents with specialized biomedical knowledge. Built following the Model Context
Protocol (MCP), it connects AI systems to authoritative biomedical data
sources, enabling them to answer questions about clinical trials, scientific
literature, and genomic variants with precision and depth.
[](https://www.youtube.com/watch?v=bKxOWrWUUhM)
## MCP Review Certification
BioMCP is certified by [MCP Review](https://mcpreview.com/mcp-servers/genomoncology/biomcp). This certification ensures that BioMCP follows best practices for Model Context Protocol implementation and provides reliable biomedical data access.
## Why BioMCP?
While Large Language Models have broad general knowledge, they often lack
specialized domain-specific information or access to up-to-date resources.
BioMCP bridges this gap for biomedicine by:
- Providing **structured access** to clinical trials, biomedical literature,
and genomic variants
- Enabling **natural language queries** to specialized databases without
requiring knowledge of their specific syntax
- Supporting **biomedical research** workflows through a consistent interface
- Functioning as an **MCP server** for AI assistants and agents
## Biomedical Data Sources
BioMCP integrates with multiple biomedical data sources:
### Literature Sources
- **PubTator3/PubMed** - Peer-reviewed biomedical literature with entity annotations
- **bioRxiv/medRxiv** - Preprint servers for biology and health sciences
- **Europe PMC** - Open science platform including preprints
### Clinical & Genomic Sources
- **ClinicalTrials.gov** - Clinical trial registry and results database
- **MyVariant.info** - Consolidated genetic variant annotation
- **TCGA/GDC** - The Cancer Genome Atlas for cancer variant data
- **1000 Genomes** - Population frequency data via Ensembl
- **cBioPortal** - Cancer genomics portal with mutation occurrence data
## Available MCP Tools
BioMCP provides 13 specialized tools for biomedical research:
### Core Tools (3)
#### 1. Think Tool (ALWAYS USE FIRST!)
**CRITICAL**: The `think` tool MUST be your first step for ANY biomedical research task.
```python
# Start analysis with sequential thinking
think(
thought="Breaking down the query about BRAF mutations in melanoma...",
thoughtNumber=1,
totalThoughts=3,
nextThoughtNeeded=True
)
```
The sequential thinking tool helps:
- Break down complex biomedical problems systematically
- Plan multi-step research approaches
- Track reasoning progress
- Ensure comprehensive analysis
#### 2. Search Tool
The search tool supports two modes:
##### Unified Query Language (Recommended)
Use the `query` parameter with structured field syntax for powerful cross-domain searches:
```python
# Simple natural language
search(query="BRAF melanoma")
# Field-specific search
search(query="gene:BRAF AND trials.condition:melanoma")
# Complex queries
search(query="gene:BRAF AND variants.significance:pathogenic AND articles.date:>2023")
# Get searchable fields schema
search(get_schema=True)
# Explain how a query is parsed
search(query="gene:BRAF", explain_query=True)
```
**Supported Fields:**
- **Cross-domain**: `gene:`, `variant:`, `disease:`
- **Trials**: `trials.condition:`, `trials.phase:`, `trials.status:`, `trials.intervention:`
- **Articles**: `articles.author:`, `articles.journal:`, `articles.date:`
- **Variants**: `variants.significance:`, `variants.rsid:`, `variants.frequency:`
##### Domain-Based Search
Use the `domain` parameter with specific filters:
```python
# Search articles (includes automatic cBioPortal integration)
search(domain="article", genes=["BRAF"], diseases=["melanoma"])
# Search with mutation-specific cBioPortal data
search(domain="article", genes=["BRAF"], keywords=["V600E"])
search(domain="article", genes=["SRSF2"], keywords=["F57*"]) # Wildcard patterns
# Search trials
search(domain="trial", conditions=["lung cancer"], phase="3")
# Search variants
search(domain="variant", gene="TP53", significance="pathogenic")
```
**Note**: When searching articles with a gene parameter, cBioPortal data is automatically included:
- Gene-level summaries show mutation frequency across cancer studies
- Mutation-specific searches (e.g., "V600E") show study-level occurrence data
- Cancer types are dynamically resolved from cBioPortal API
#### 3. Fetch Tool
Retrieve full details for a single article, trial, or variant:
```python
# Fetch article details (supports both PMID and DOI)
fetch(domain="article", id="34567890") # PMID
fetch(domain="article", id="10.1101/2024.01.20.23288905") # DOI
# Fetch trial with all sections
fetch(domain="trial", id="NCT04280705", detail="all")
# Fetch variant details
fetch(domain="variant", id="rs113488022")
```
**Domain-specific options:**
- **Articles**: `detail="full"` retrieves full text if available
- **Trials**: `detail` can be "protocol", "locations", "outcomes", "references", or "all"
- **Variants**: Always returns full details
### Individual Tools (10)
For users who prefer direct access to specific functionality, BioMCP also provides 10 individual tools:
#### Article Tools (2)
- **article_searcher**: Search PubMed/PubTator3 and preprints
- **article_getter**: Fetch detailed article information (supports PMID and DOI)
#### Trial Tools (5)
- **trial_searcher**: Search ClinicalTrials.gov
- **trial_getter**: Fetch all trial details
- **trial_protocol_getter**: Fetch protocol information only
- **trial_references_getter**: Fetch trial publications
- **trial_outcomes_getter**: Fetch outcome measures and results
- **trial_locations_getter**: Fetch site locations and contacts
#### Variant Tools (2)
- **variant_searcher**: Search MyVariant.info database
- **variant_getter**: Fetch comprehensive variant details
**Note**: All individual tools that search by gene automatically include cBioPortal summaries when the `include_cbioportal` parameter is True (default).
## Quick Start
### For Claude Desktop Users
1. **Install `uv`** if you don't have it (recommended):
```bash
# MacOS
brew install uv
# Windows/Linux
pip install uv
```
2. **Configure Claude Desktop**:
- Open Claude Desktop settings
- Navigate to Developer section
- Click "Edit Config" and add:
```json
{
"mcpServers": {
"biomcp": {
"command": "uv",
"args": ["run", "--with", "biomcp-python", "biomcp", "run"]
}
}
}
```
- Restart Claude Desktop and start chatting about biomedical topics!
### Python Package Installation
```bash
# Using pip
pip install biomcp-python
# Using uv (recommended for faster installation)
uv pip install biomcp-python
# Run directly without installation
uv run --with biomcp-python biomcp trial search --condition "lung cancer"
```
## Configuration
### Environment Variables
BioMCP supports optional environment variables for enhanced functionality:
```bash
# cBioPortal API authentication (optional)
export CBIO_TOKEN="your-api-token" # For authenticated access
export CBIO_BASE_URL="https://www.cbioportal.org/api" # Custom API endpoint
```
Note: All APIs work without authentication, but tokens may provide higher rate limits.
## Command Line Interface
BioMCP provides a comprehensive CLI for direct database interaction:
```bash
# Get help
biomcp --help
# Run the MCP server
biomcp run
# Article search examples
biomcp article search --gene BRAF --disease Melanoma # Includes preprints by default
biomcp article search --gene BRAF --no-preprints # Exclude preprints
biomcp article get 21717063 --full
# Clinical trial examples
biomcp trial search --condition "Lung Cancer" --phase PHASE3
biomcp trial get NCT04280705 Protocol
# Variant examples with external annotations
biomcp variant search --gene TP53 --significance pathogenic
biomcp variant get rs113488022 # Includes TCGA, 1000 Genomes, and cBioPortal data by default
biomcp variant get rs113488022 --no-external # Core annotations only
```
## Testing & Verification
Test your BioMCP setup with the MCP Inspector:
```bash
npx @modelcontextprotocol/inspector uv run --with biomcp-python biomcp run
```
This opens a web interface where you can explore and test all available tools.
## Enterprise Version: OncoMCP
OncoMCP extends BioMCP with GenomOncology's enterprise-grade precision oncology
platform (POP), providing:
- **HIPAA-Compliant Deployment**: Secure on-premise options
- **Real-Time Trial Matching**: Up-to-date status and arm-level matching
- **Healthcare Integration**: Seamless EHR and data warehouse connectivity
- **Curated Knowledge Base**: 15,000+ trials and FDA approvals
- **Sophisticated Patient Matching**: Using integrated clinical and molecular
profiles
- **Advanced NLP**: Structured extraction from unstructured text
- **Comprehensive Biomarker Processing**: Mutation and rule processing
Learn more: [GenomOncology](https://genomoncology.com/)
## MCP Registries
[](https://smithery.ai/server/@genomoncology/biomcp)
<a href="https://glama.ai/mcp/servers/@genomoncology/biomcp">
<img width="380" height="200" src="https://glama.ai/mcp/servers/@genomoncology/biomcp/badge" />
</a>
## Documentation
For comprehensive documentation, visit [https://biomcp.org](https://biomcp.org)
## BioMCP Examples Repo
Looking to see BioMCP in action?
Check out the companion repository:
👉 **[biomcp-examples](https://github.com/genomoncology/biomcp-examples)**
It contains real prompts, AI-generated research briefs, and evaluation runs across different models.
Use it to explore capabilities, compare outputs, or benchmark your own setup.
Have a cool example of your own?
**We’d love for you to contribute!** Just fork the repo and submit a PR with your experiment.
## License
This project is licensed under the MIT License.
Raw data
{
"_id": null,
"home_page": null,
"name": "biomcp-python",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "python",
"author": null,
"author_email": "Ian Maurer <imaurer@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/12/16/db3a367cb30348116dedd1dff661b07c1fd9c38617a4d5689e6066cad2d2/biomcp_python-0.4.3.tar.gz",
"platform": null,
"description": "# BioMCP: Biomedical Model Context Protocol\n\nBioMCP is an open source (MIT License) toolkit that empowers AI assistants and\nagents with specialized biomedical knowledge. Built following the Model Context\nProtocol (MCP), it connects AI systems to authoritative biomedical data\nsources, enabling them to answer questions about clinical trials, scientific\nliterature, and genomic variants with precision and depth.\n\n[](https://www.youtube.com/watch?v=bKxOWrWUUhM)\n\n## MCP Review Certification\n\nBioMCP is certified by [MCP Review](https://mcpreview.com/mcp-servers/genomoncology/biomcp). This certification ensures that BioMCP follows best practices for Model Context Protocol implementation and provides reliable biomedical data access.\n\n## Why BioMCP?\n\nWhile Large Language Models have broad general knowledge, they often lack\nspecialized domain-specific information or access to up-to-date resources.\nBioMCP bridges this gap for biomedicine by:\n\n- Providing **structured access** to clinical trials, biomedical literature,\n and genomic variants\n- Enabling **natural language queries** to specialized databases without\n requiring knowledge of their specific syntax\n- Supporting **biomedical research** workflows through a consistent interface\n- Functioning as an **MCP server** for AI assistants and agents\n\n## Biomedical Data Sources\n\nBioMCP integrates with multiple biomedical data sources:\n\n### Literature Sources\n\n- **PubTator3/PubMed** - Peer-reviewed biomedical literature with entity annotations\n- **bioRxiv/medRxiv** - Preprint servers for biology and health sciences\n- **Europe PMC** - Open science platform including preprints\n\n### Clinical & Genomic Sources\n\n- **ClinicalTrials.gov** - Clinical trial registry and results database\n- **MyVariant.info** - Consolidated genetic variant annotation\n- **TCGA/GDC** - The Cancer Genome Atlas for cancer variant data\n- **1000 Genomes** - Population frequency data via Ensembl\n- **cBioPortal** - Cancer genomics portal with mutation occurrence data\n\n## Available MCP Tools\n\nBioMCP provides 13 specialized tools for biomedical research:\n\n### Core Tools (3)\n\n#### 1. Think Tool (ALWAYS USE FIRST!)\n\n**CRITICAL**: The `think` tool MUST be your first step for ANY biomedical research task.\n\n```python\n# Start analysis with sequential thinking\nthink(\n thought=\"Breaking down the query about BRAF mutations in melanoma...\",\n thoughtNumber=1,\n totalThoughts=3,\n nextThoughtNeeded=True\n)\n```\n\nThe sequential thinking tool helps:\n\n- Break down complex biomedical problems systematically\n- Plan multi-step research approaches\n- Track reasoning progress\n- Ensure comprehensive analysis\n\n#### 2. Search Tool\n\nThe search tool supports two modes:\n\n##### Unified Query Language (Recommended)\n\nUse the `query` parameter with structured field syntax for powerful cross-domain searches:\n\n```python\n# Simple natural language\nsearch(query=\"BRAF melanoma\")\n\n# Field-specific search\nsearch(query=\"gene:BRAF AND trials.condition:melanoma\")\n\n# Complex queries\nsearch(query=\"gene:BRAF AND variants.significance:pathogenic AND articles.date:>2023\")\n\n# Get searchable fields schema\nsearch(get_schema=True)\n\n# Explain how a query is parsed\nsearch(query=\"gene:BRAF\", explain_query=True)\n```\n\n**Supported Fields:**\n\n- **Cross-domain**: `gene:`, `variant:`, `disease:`\n- **Trials**: `trials.condition:`, `trials.phase:`, `trials.status:`, `trials.intervention:`\n- **Articles**: `articles.author:`, `articles.journal:`, `articles.date:`\n- **Variants**: `variants.significance:`, `variants.rsid:`, `variants.frequency:`\n\n##### Domain-Based Search\n\nUse the `domain` parameter with specific filters:\n\n```python\n# Search articles (includes automatic cBioPortal integration)\nsearch(domain=\"article\", genes=[\"BRAF\"], diseases=[\"melanoma\"])\n\n# Search with mutation-specific cBioPortal data\nsearch(domain=\"article\", genes=[\"BRAF\"], keywords=[\"V600E\"])\nsearch(domain=\"article\", genes=[\"SRSF2\"], keywords=[\"F57*\"]) # Wildcard patterns\n\n# Search trials\nsearch(domain=\"trial\", conditions=[\"lung cancer\"], phase=\"3\")\n\n# Search variants\nsearch(domain=\"variant\", gene=\"TP53\", significance=\"pathogenic\")\n```\n\n**Note**: When searching articles with a gene parameter, cBioPortal data is automatically included:\n\n- Gene-level summaries show mutation frequency across cancer studies\n- Mutation-specific searches (e.g., \"V600E\") show study-level occurrence data\n- Cancer types are dynamically resolved from cBioPortal API\n\n#### 3. Fetch Tool\n\nRetrieve full details for a single article, trial, or variant:\n\n```python\n# Fetch article details (supports both PMID and DOI)\nfetch(domain=\"article\", id=\"34567890\") # PMID\nfetch(domain=\"article\", id=\"10.1101/2024.01.20.23288905\") # DOI\n\n# Fetch trial with all sections\nfetch(domain=\"trial\", id=\"NCT04280705\", detail=\"all\")\n\n# Fetch variant details\nfetch(domain=\"variant\", id=\"rs113488022\")\n```\n\n**Domain-specific options:**\n\n- **Articles**: `detail=\"full\"` retrieves full text if available\n- **Trials**: `detail` can be \"protocol\", \"locations\", \"outcomes\", \"references\", or \"all\"\n- **Variants**: Always returns full details\n\n### Individual Tools (10)\n\nFor users who prefer direct access to specific functionality, BioMCP also provides 10 individual tools:\n\n#### Article Tools (2)\n\n- **article_searcher**: Search PubMed/PubTator3 and preprints\n- **article_getter**: Fetch detailed article information (supports PMID and DOI)\n\n#### Trial Tools (5)\n\n- **trial_searcher**: Search ClinicalTrials.gov\n- **trial_getter**: Fetch all trial details\n- **trial_protocol_getter**: Fetch protocol information only\n- **trial_references_getter**: Fetch trial publications\n- **trial_outcomes_getter**: Fetch outcome measures and results\n- **trial_locations_getter**: Fetch site locations and contacts\n\n#### Variant Tools (2)\n\n- **variant_searcher**: Search MyVariant.info database\n- **variant_getter**: Fetch comprehensive variant details\n\n**Note**: All individual tools that search by gene automatically include cBioPortal summaries when the `include_cbioportal` parameter is True (default).\n\n## Quick Start\n\n### For Claude Desktop Users\n\n1. **Install `uv`** if you don't have it (recommended):\n\n ```bash\n # MacOS\n brew install uv\n\n # Windows/Linux\n pip install uv\n ```\n\n2. **Configure Claude Desktop**:\n - Open Claude Desktop settings\n - Navigate to Developer section\n - Click \"Edit Config\" and add:\n ```json\n {\n \"mcpServers\": {\n \"biomcp\": {\n \"command\": \"uv\",\n \"args\": [\"run\", \"--with\", \"biomcp-python\", \"biomcp\", \"run\"]\n }\n }\n }\n ```\n - Restart Claude Desktop and start chatting about biomedical topics!\n\n### Python Package Installation\n\n```bash\n# Using pip\npip install biomcp-python\n\n# Using uv (recommended for faster installation)\nuv pip install biomcp-python\n\n# Run directly without installation\nuv run --with biomcp-python biomcp trial search --condition \"lung cancer\"\n```\n\n## Configuration\n\n### Environment Variables\n\nBioMCP supports optional environment variables for enhanced functionality:\n\n```bash\n# cBioPortal API authentication (optional)\nexport CBIO_TOKEN=\"your-api-token\" # For authenticated access\nexport CBIO_BASE_URL=\"https://www.cbioportal.org/api\" # Custom API endpoint\n```\n\nNote: All APIs work without authentication, but tokens may provide higher rate limits.\n\n## Command Line Interface\n\nBioMCP provides a comprehensive CLI for direct database interaction:\n\n```bash\n# Get help\nbiomcp --help\n\n# Run the MCP server\nbiomcp run\n\n# Article search examples\nbiomcp article search --gene BRAF --disease Melanoma # Includes preprints by default\nbiomcp article search --gene BRAF --no-preprints # Exclude preprints\nbiomcp article get 21717063 --full\n\n# Clinical trial examples\nbiomcp trial search --condition \"Lung Cancer\" --phase PHASE3\nbiomcp trial get NCT04280705 Protocol\n\n# Variant examples with external annotations\nbiomcp variant search --gene TP53 --significance pathogenic\nbiomcp variant get rs113488022 # Includes TCGA, 1000 Genomes, and cBioPortal data by default\nbiomcp variant get rs113488022 --no-external # Core annotations only\n```\n\n## Testing & Verification\n\nTest your BioMCP setup with the MCP Inspector:\n\n```bash\nnpx @modelcontextprotocol/inspector uv run --with biomcp-python biomcp run\n```\n\nThis opens a web interface where you can explore and test all available tools.\n\n## Enterprise Version: OncoMCP\n\nOncoMCP extends BioMCP with GenomOncology's enterprise-grade precision oncology\nplatform (POP), providing:\n\n- **HIPAA-Compliant Deployment**: Secure on-premise options\n- **Real-Time Trial Matching**: Up-to-date status and arm-level matching\n- **Healthcare Integration**: Seamless EHR and data warehouse connectivity\n- **Curated Knowledge Base**: 15,000+ trials and FDA approvals\n- **Sophisticated Patient Matching**: Using integrated clinical and molecular\n profiles\n- **Advanced NLP**: Structured extraction from unstructured text\n- **Comprehensive Biomarker Processing**: Mutation and rule processing\n\nLearn more: [GenomOncology](https://genomoncology.com/)\n\n## MCP Registries\n\n[](https://smithery.ai/server/@genomoncology/biomcp)\n\n<a href=\"https://glama.ai/mcp/servers/@genomoncology/biomcp\">\n<img width=\"380\" height=\"200\" src=\"https://glama.ai/mcp/servers/@genomoncology/biomcp/badge\" />\n</a>\n\n## Documentation\n\nFor comprehensive documentation, visit [https://biomcp.org](https://biomcp.org)\n\n## BioMCP Examples Repo\n\nLooking to see BioMCP in action?\n\nCheck out the companion repository:\n\ud83d\udc49 **[biomcp-examples](https://github.com/genomoncology/biomcp-examples)**\n\nIt contains real prompts, AI-generated research briefs, and evaluation runs across different models.\nUse it to explore capabilities, compare outputs, or benchmark your own setup.\n\nHave a cool example of your own?\n**We\u2019d love for you to contribute!** Just fork the repo and submit a PR with your experiment.\n\n## License\n\nThis project is licensed under the MIT License.\n",
"bugtrack_url": null,
"license": null,
"summary": "Biomedical Model Context Protocol Server",
"version": "0.4.3",
"project_urls": {
"Documentation": "https://genomoncology.com/biomcp/",
"Homepage": "https://genomoncology.com/biomcp/",
"Repository": "https://github.com/genomoncology/biomcp"
},
"split_keywords": [
"python"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d7f2942f8d532d0a180f9dbdd3be599fbe311c24b3bfb98a12cca6acc5dcb7f7",
"md5": "2985940920341c24a36ee2be82703b34",
"sha256": "2ae2463942bf104baf5c0e8dc738546248d46e87c4201df613c441b97784c989"
},
"downloads": -1,
"filename": "biomcp_python-0.4.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2985940920341c24a36ee2be82703b34",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 146856,
"upload_time": "2025-07-08T15:21:49",
"upload_time_iso_8601": "2025-07-08T15:21:49.937325Z",
"url": "https://files.pythonhosted.org/packages/d7/f2/942f8d532d0a180f9dbdd3be599fbe311c24b3bfb98a12cca6acc5dcb7f7/biomcp_python-0.4.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1216db3a367cb30348116dedd1dff661b07c1fd9c38617a4d5689e6066cad2d2",
"md5": "d41af4dfee0348dbe9045bb608c500d6",
"sha256": "c0c9b18bd50556626739177d06f5a30f63cd1fba9ed12b9fc5bac7a981aaacde"
},
"downloads": -1,
"filename": "biomcp_python-0.4.3.tar.gz",
"has_sig": false,
"md5_digest": "d41af4dfee0348dbe9045bb608c500d6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 127250,
"upload_time": "2025-07-08T15:21:51",
"upload_time_iso_8601": "2025-07-08T15:21:51.845989Z",
"url": "https://files.pythonhosted.org/packages/12/16/db3a367cb30348116dedd1dff661b07c1fd9c38617a4d5689e6066cad2d2/biomcp_python-0.4.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-08 15:21:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "genomoncology",
"github_project": "biomcp",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "biomcp-python"
}
