BioMCP

BioMCP

Un solo binario. Una sola gramática. Evidencia de las fuentes biomédicas en las que ya confías.

Términos de los datos

BioMCP recupera datos de fuentes biomédicas upstream. Los términos de esas fuentes rigen cómo usas los datos que devuelven: algunas restringen el uso comercial o clínico. Consulta los términos de cada fuente y obtén la licencia que necesites antes de confiar en los datos. Consulta Licencias y términos de las fuentes para el desglose por fuente.

¿Qué es BioMCP?

BioMCP es un único binario CLI sobre una gramática de comandos única que accede directamente a 70 fuentes biomédicas de confianza (PubMed, ClinVar, ClinicalTrials.gov, OncoKB, Reactome y más; otras diez fuentes llegan dentro de la respuesta de otra fuente). También es un servidor MCP (Model Context Protocol), por lo que las mismas herramientas están disponibles para agentes de IA como Claude Code, Codex y Claude Desktop.

BioMCP atraviesa el laberinto habitual de datos biomédicos: una sola consulta llega a las fuentes que normalmente viven detrás de diferentes APIs, identificadores y hábitos de búsqueda. Investigadores, clínicos y agentes usan la misma gramática de comandos para buscar, enfocar y pivotar sin reconstruir el flujo de trabajo para cada fuente. Obtienes resultados compactos y orientados a la evidencia en datos públicos en vivo más análisis locales de estudios.

Características

• Busca en la literatura: search article se expande a través de PubTator3 y Europe PMC, deduplica identificadores PMID/PMCID/DOI y puede añadir una vía de Semantic Scholar cuando tus filtros lo permiten.
• Pivota sin rehacer: pasa de un gen, variante, fármaco, enfermedad, vía, proteína o artículo directamente a la siguiente vista integrada en lugar de reconstruir filtros manualmente.
• Elige un manual: biomcp skill list muestra ejemplos prácticos incluidos para que puedas abrir el flujo de trabajo biomcp skill <slug> correspondiente.
• Analiza estudios localmente: los comandos study cubren flujos de trabajo locales de consulta, cohorte, supervivencia, comparación y co-ocurrencia con gráficos nativos en terminal, SVG y PNG para conjuntos de datos descargados estilo cBioPortal.
• Sigue el rastro del artículo: article citations, article references, article recommendations y article entities convierten un artículo conocido en un mapa de evidencia más amplio.
• Enriquece y procesa por lotes: usa biomcp enrich para enriquecimiento de nivel superior con g:Profiler y biomcp batch para hasta 10 llamadas enfocadas de get en un solo comando.

Inicio rápido

Primera consulta útil en menos de 30 segundos:

uv tool install biomcp-cli
biomcp health --apis-only
biomcp skill list
biomcp list gene
biomcp search all --gene BRAF --disease melanoma  # unified cross-entity discovery
biomcp get gene BRAF pathways hpa

Mira la introducción

Un proyecto que usa BioMCP ganó el KIDS BioHackathon de St. Jude en 2025. La charla que siguió es una introducción de una hora a BioMCP, grabada el 24 de octubre de 2025.

Ver en YouTube · Leer el artículo · Transcripción completa

Instalación

Instalación del binario

curl -fsSL https://biomcp.org/install.sh | bash

Instalación como herramienta PyPI

uv tool install biomcp-cli
# or: pip install biomcp-cli

Advertencia sobre el paquete PyPI: instala biomcp-cli, no biomcp. El paquete PyPI biomcp no está relacionado con este proyecto.

Marcador de propiedad del Registro MCP: mcp-name: io.github.genomoncology/biomcp.

Esto instala el binario biomcp en ~/.local/bin. Si ese directorio no está ya en PATH, el instalador imprime un comando para añadirlo; nunca edita tus archivos de inicio del shell.

Homebrew

brew tap genomoncology/biomcp
brew install biomcp

El repositorio de tap genomoncology/homebrew-biomcp separado debe existir antes de que estos comandos puedan funcionar.

Docker

docker run --rm ghcr.io/genomoncology/biomcp --version
docker run --rm ghcr.io/genomoncology/biomcp list
docker run --rm -i ghcr.io/genomoncology/biomcp serve

Usa la imagen GHCR para comprobaciones rápidas de CLI o clientes MCP stdio sin instalación local.

Plugin de Claude Code

Instala primero el binario biomcp, luego añade el marketplace de plugins alojado e instala el plugin de BioMCP en Claude Code:

/plugin marketplace add genomoncology/biomcp
/plugin install biomcp@biomcp

El plugin conecta Claude Code al servidor MCP stdio local con biomcp serve. Para flujos de trabajo guiados de BioMCP, instala también los recursos de habilidades a continuación.

Servidor MCP de Codex

Instala primero el binario biomcp, luego registra el mismo servidor MCP stdio con Codex:

codex mcp add biomcp -- biomcp serve

Extensión de Claude Desktop (.mcpb)

Instala BioMCP desde el Directorio de Anthropic en Claude Desktop cuando esa ruta esté disponible para tu entorno. Para configuraciones locales/manuales, usa la configuración JSON MCP a continuación.

Instalar habilidades

Instala flujos de trabajo de investigación guiados en tu directorio de agente:

biomcp skill install ~/.claude --force

Clientes MCP

{
  "mcpServers": {
    "biomcp": {
      "command": "biomcp",
      "args": ["serve"]
    }
  }
}

Servidor HTTP remoto

Para implementaciones compartidas o remotas:

biomcp serve-http --host 127.0.0.1 --port 8080

Los clientes remotos se conectan a http://127.0.0.1:8080/mcp. Las rutas de sondeo son GET /health, GET /readyz y GET /.

Demo ejecutable:

uv run --script examples/streamable-http/streamable_http_client.py

Consulta Servidor HTTP remoto para la guía para principiantes.

Desde el código fuente

make install
"$HOME/.local/bin/biomcp" --version

Para verificación local del repositorio, ejecuta las compuertas estándar directamente: make lint, make test y make spec. make test incluye tanto Rust nextest como el carril de contrato de Python/docs, mientras que make release-gate añade la prueba de características completas nombrada y ejecuta especificaciones contra el binario de lanzamiento con todas las características. No hay un comando make check compatible. Usa make verify solo para confianza opt-in en upstream público en vivo; make release-live-smoke sigue siendo un alias de compatibilidad.

Gramática de comandos

search <entity> [filters]    → discovery
skill list                   → playbook catalog for how-to questions
discover <query>             → concept resolution before entity selection
get <entity> <id> [sections] → focused detail
<entity> <helper> <id>       → cross-entity pivots
enrich <GENE1,GENE2,...>     → gene-set enrichment
batch <entity> <id1,id2,...> → parallel gets
search all [slot filters]    → counts-first cross-entity orientation

Entidades y fuentes

Las tablas siguientes distinguen las entidades de tarjeta de detalle de las superficies solo de búsqueda para que los agentes no sinteticen comandos get no compatibles.

Entidades obtenibles

Entidad	Proveedores upstream usados por BioMCP	Ejemplo
gen	MyGene.info, UniProt, Reactome, QuickGO, STRING, GTEx, Human Protein Atlas, DGIdb, ClinGen, NIH Reporter, DisGeNET, pivote de diagnóstico respaldado por GTR	biomcp get gene BRAF pathways hpa
variante	MyVariant.info, ClinVar, datos de población directos de gnomAD v4, CIViC, Cancer Genome Interpreter, OncoKB, cBioPortal, GWAS Catalog, AlphaGenome	biomcp get variant "BRAF V600E" clinvar
artículo	PubMed, PubTator3, Europe PMC, PMC OA, NCBI ID Converter, Semantic Scholar (auth opcional; se recomienda S2_API_KEY)	biomcp search article -g BRAF --limit 5
autor	Semantic Scholar, ORCID	biomcp get author semanticscholar:1716151
ensayo	API v2 de ClinicalTrials.gov, API NCI CTS	biomcp search trial -c melanoma -s recruiting
diagnóstico	Paquete local de NCBI Genetic Testing Registry + CSV local de IVD de la OMS + superposición opcional de dispositivos OpenFDA	biomcp get diagnostic GTR000006692.3 regulatory
fármaco	MyChem.info, paquete local DDInter, lote local EMA, exportaciones locales de Prequalificación de la OMS, ChEMBL, OpenTargets, Drugs@FDA, etiquetas/escaseces/aprobaciones/FAERS/MAUDE/retiros de OpenFDA, CIViC	biomcp drug interactions warfarin
enfermedad	MyDisease.info, Monarch Initiative, MONDO, OpenTargets, Reactome, CIViC, SEER Explorer, NIH Reporter, DisGeNET, pivote de diagnóstico GTR/IVD de la OMS	biomcp get disease "Lynch syndrome" genes
vía	Reactome, KEGG, WikiPathways, g:Profiler, secciones de enriquecimiento respaldadas por Enrichr	biomcp get pathway hsa05200 genes
proteína	UniProt, InterPro, STRING, ComplexPortal, PDB, AlphaFold	biomcp get protein P15056 complexes
evento adverso	FAERS/MAUDE/retiros de OpenFDA más búsqueda agregada de vacunas VAERS de CDC WONDER	biomcp search adverse-event --drug pembrolizumab
pgx	CPIC, PharmGKB	biomcp get pgx CYP2D6 recommendations
línea celular	Cellosaurus con referencias cruzadas de ChEMBL, PharmacoDB, DepMap, COSMIC, GDSC y LINCS	biomcp get cell-line CVCL_0004 xrefs

Entidades solo de búsqueda

Entidad	Proveedores upstream usados por BioMCP	Ejemplo
gwas	GWAS Catalog	biomcp search gwas --trait "type 2 diabetes"
fenotipo	Monarch Initiative (similitud semántica HPO más comprobaciones de soporte directo)	biomcp search phenotype "HP:0001250"

Ayudantes entre entidades

Pivota entre entidades relacionadas sin reconstruir filtros.

Consulta la guía de pivote entre entidades para saber cuándo usar un ayudante frente a una búsqueda nueva.

biomcp variant trials "BRAF V600E" --limit 5
biomcp variant articles "BRAF V600E"
biomcp drug adverse-events pembrolizumab
biomcp drug trials pembrolizumab
biomcp disease trials melanoma
biomcp disease drugs melanoma
biomcp disease articles "Lynch syndrome"
biomcp gene trials BRAF
biomcp gene drugs BRAF
biomcp gene articles BRCA1
biomcp gene pathways BRAF
biomcp pathway drugs R-HSA-5673001
biomcp pathway drugs hsa05200
biomcp pathway articles R-HSA-5673001
biomcp pathway trials R-HSA-5673001
biomcp protein structures P15056
biomcp article entities 22663011
biomcp article citations 22663011 --limit 3
biomcp article references 22663011 --limit 3
biomcp article recommendations 22663011 --limit 3

Enriquecimiento de conjuntos de genes

biomcp enrich BRAF,KRAS,NRAS --limit 10

El biomcp enrich de nivel superior usa g:Profiler. Las secciones de enriquecimiento de genes dentro de otras vistas de entidades siguen referenciando Enrichr donde esa es la fuente subyacente.

Secciones y divulgación progresiva

Cada comando get admite secciones seleccionables para una salida enfocada:

biomcp get gene BRAF                    # summary card
biomcp get gene BRAF pathways           # add pathway section
biomcp get gene BRCA1 diagnostics       # diagnostic-test pivot from GTR
biomcp get gene BRAF hpa                # protein tissue expression + localization
biomcp get gene BRAF civic interactions # multiple sections
biomcp get gene BRAF all                # standard sections; diagnostics/funding stay opt-in

biomcp get variant "BRAF V600E" clinvar population conservation
biomcp get article 22663011 tldr
biomcp get drug pembrolizumab label targets civic approvals
biomcp get drug trastuzumab regulatory --region who
biomcp get disease "Lynch syndrome" genes phenotypes variants
biomcp get disease tuberculosis diagnostics
biomcp get diagnostic GTR000006692.3 regulatory
biomcp get trial NCT02576665 eligibility locations outcomes

En modo JSON, las respuestas de get exponen _meta.next_commands para los próximos seguimientos probables y _meta.section_sources para la procedencia a nivel de sección. batch ... --json devuelve objetos por entidad con la misma forma de metadatos.

Claves API

La mayoría de los comandos funcionan sin credenciales. Las claves opcionales mejoran los límites de velocidad o desbloquean enriquecimientos opcionales:

export NCBI_API_KEY="..."        # ClinVar, PubTator, PubMed/efetch, PMC OA, NCBI ID converter
export S2_API_KEY="..."          # Optional Semantic Scholar auth; dedicated quota at 1 req/sec
export OPENFDA_API_KEY="..."     # OpenFDA rate limits
export NCI_API_KEY="..."         # NCI CTS trial search (--source nci)
export ONCOKB_TOKEN="..."        # OncoKB variant helper
export ALPHAGENOME_API_KEY="..." # AlphaGenome variant effect prediction

search article, get article, batch article, get article ... tldr y los ayudantes explícitos de Semantic Scholar funcionan todos sin S2_API_KEY. Con la clave, BioMCP envía solicitudes autenticadas y usa un límite de velocidad dedicado de 1 req/seg. Sin ella, BioMCP usa el grupo compartido no autenticado de 1 req/2 seg. search article --source admite all, pubtator, europepmc, pubmed, semanticscholar y litsense2. La federación de artículos compatible predeterminada usa PubTator3, Europe PMC, PubMed y Semantic Scholar automático; usa --source semanticscholar o --source litsense2 explícitamente cuando quieras una de esas fuentes sola. La selección explícita de fuente también desactiva el enriquecimiento de filas entre proveedores. Las referencias y recomendaciones pueden estar vacías para artículos con muro de pago debido a la elisión del editor en la cobertura upstream de Semantic Scholar.

Configuración

Configuración de la extensión de Claude Desktop

El paquete de directorio expone solo la configuración opcional necesaria para la primera compilación orientada a revisores:

Campo de Claude Desktop	Variable de entorno en runtime	Propósito
OncoKB Token	ONCOKB_TOKEN	Habilita la evidencia de terapia y nivel de biomcp variant oncokb "<gene> <variant>"
DisGeNET API Key	DISGENET_API_KEY	Habilita secciones puntuadas de DisGeNET en búsquedas de genes y enfermedades
Semantic Scholar API Key	S2_API_KEY	Mejora la fiabilidad de los ayudantes de TLDR, citas, referencias y recomendaciones de artículos

La primera compilación del directorio expone solo esas tres configuraciones opcionales. Las variables de entorno avanzadas solo CLI siguen documentadas en Claves API para la ruta general de CLI de BioMCP.

Ejemplos de uso

Resumen público entre entidades

Solicitud del usuario: Dame un resumen de bajo ruido de BRAF en melanoma.

Llamada de herramienta esperada: biomcp search all --gene BRAF --disease melanoma --counts-only

Comportamiento esperado: Devuelve un resumen de recuentos entre entidades que orienta el siguiente comando en lugar de volcar tablas de detalles largas.

Salida esperada: Resumen primero con recuentos y comandos siguientes sugeridos para los seguimientos de entidades de mayor rendimiento.

Evidencia pública de variantes

Solicitud del usuario: Resume la significancia de ClinVar y la frecuencia poblacional de BRAF V600E.

Llamada de herramienta esperada: biomcp get variant "BRAF V600E" clinvar population

Comportamiento esperado: Recupera la tarjeta de variante enfocada, la sección de ClinVar y los datos de frecuencia poblacional en una sola llamada de solo lectura.

Salida esperada: Resumen de variante, detalles de significancia de ClinVar y frecuencias poblacionales de gnomAD.

Ejemplo con credenciales de OncoKB

Solicitud del usuario: Muestra la evidencia de terapia de OncoKB para BRAF V600E.

Llamada de herramienta esperada: biomcp variant oncokb "BRAF V600E"

Comportamiento esperado: Usa ONCOKB_TOKEN cuando está configurado y, de lo contrario, devuelve orientación útil sobre la credencial faltante.

Salida esperada: Evidencia de terapia y nivel cuando ONCOKB_TOKEN está configurado, o una pista de configuración clara cuando no lo está.

Ejemplo con credenciales de DisGeNET

Solicitud del usuario: Muestra las asociaciones puntuadas de DisGeNET para TP53.

Llamada de herramienta esperada: biomcp get gene TP53 disgenet

Comportamiento esperado: Usa DISGENET_API_KEY para recuperar la sección puntuada de asociación gen-enfermedad.

Salida esperada: Tabla de asociaciones de enfermedades clasificadas con recuentos de evidencia y puntuaciones cuando DISGENET_API_KEY está configurado.

Política de privacidad

BioMCP no añade telemetría, análisis ni carga de registros remota. Revisa la declaración de privacidad completa en https://biomcp.org/policies/.

Implementación multi-trabajador

La limitación de velocidad de BioMCP es local al proceso. Para muchos trabajadores concurrentes, ejecuta un único endpoint biomcp serve-http Streamable HTTP compartido para que todos los trabajadores compartan un único presupuesto de limitador:

biomcp serve-http --host 0.0.0.0 --port 8080 \
  --allowed-hosts biomcp.example.org

Los servidores de bucle local aceptan solo valores locales de Host por defecto. Un enlace que no sea de bucle local requiere --allowed-hosts. La vía de escape explícita --unsafe-allow-any-host desactiva solo esta verificación de Host; no añade autenticación, TLS ni cifrado. Coloque los despliegues remotos detrás de un proxy TLS autenticado y confiable o dentro de una red privada.

Los clientes remotos deben conectarse a http://<host>:8080/mcp. Hay sondas de proceso ligeras disponibles en GET /health, GET /readyz y GET /.

Habilidades

BioMCP incluye una guía de agente integrada y un catálogo de ejemplos trabajados. Use biomcp skill list cuando necesite el ejemplo trabajado correcto, luego use biomcp skill para leer la guía integrada de BioMCP o instalarla en su directorio de agente cuando desee copias locales de las referencias de flujo de trabajo:

biomcp skill list
biomcp skill
biomcp skill install ~/.claude --force

Consulte Habilidades para conocer los destinos de instalación compatibles, los archivos instalados y las notas de compatibilidad heredadas.

Análisis de estudio local

study es la familia de análisis local de BioMCP para conjuntos de datos descargados estilo cBioPortal. La superficie de entidades públicas maneja descubrimiento/detalle basado en API, tiempo de ejecución local e híbrido; los comandos study funcionan en conjuntos de datos locales cuando necesita flujos de trabajo de consulta por estudio, cohorte, supervivencia, comparación o co-ocurrencia. Las consultas por gen incluyen mutaciones, CNA, expresión y variantes estructurales/fusiones de archivos locales data_sv.txt. Los resúmenes de mutaciones permanecen solo con mutaciones y notan cuando las fusiones/SV necesitan --type sv.

Use study download para obtener un conjunto de datos en su raíz de estudio local. Establezca BIOMCP_STUDY_DIR cuando desee una ubicación explícita del conjunto de datos para scripts y demos reproducibles; si no está establecido, BioMCP recurre a su raíz de estudio predeterminada.

export BIOMCP_STUDY_DIR="$HOME/.local/share/biomcp/studies"
biomcp study download msk_impact_2017
biomcp study query --study msk_impact_2017 --gene TP53 --type mutations --chart bar --theme dark --palette wong -o docs/blog/images/tp53-mutation-bar.svg
biomcp study query --study msk_impact_2017 --gene RET --type sv

Consulte la referencia de CLI para la familia completa de comandos study y los requisitos previos del conjunto de datos.

Operaciones

biomcp version                            # show version and build info
biomcp health                             # inspect API connectivity plus local DDInter/EMA/cache readiness
biomcp update                             # self-update with release SHA256 checksum verification
biomcp update --check                     # check for updates without installing
biomcp uninstall                          # remove biomcp from ~/.local/bin

Soporte

• Problemas de GitHub: https://github.com/genomoncology/biomcp/issues
• Solución de problemas: docs/troubleshooting.md
• Documentación completa: https://biomcp.org/

Documentación

• Cómo empezar
• Flujo de trabajo de búsqueda completa
• Referencia de BioASQ
• Guía de pivote entre entidades
• Política de privacidad
• Licencia de fuentes y términos
• Fuentes de datos
• Referencia rápida
• Solución de problemas

Cita

Si usa BioMCP en investigación, cítelo a través de CITATION.cff. GitHub también expone Cite this repository en la barra lateral del repositorio cuando ese archivo está presente.

Fuentes de datos y licencias

BioMCP tiene licencia MIT. Realiza consultas bajo demanda contra proveedores upstream en lugar de vender o reflejar sus conjuntos de datos, pero los términos upstream rigen la reutilización de los resultados recuperados.

Algunos proveedores son completamente abiertos, algunas funciones de BioMCP requieren registro o claves de API, y algunas fuentes consultables aún imponen límites de reutilización notables. Las dos mayores advertencias son KEGG, que distingue el uso académico y no académico, y COSMIC, que BioMCP mantiene solo indirecto porque su modelo de licencia es incompatible con una integración abierta directa.

Use Licencia de fuentes y términos para el desglose por fuente y Claves de API para los pasos de configuración y enlaces de registro.

Licencia

MIT