BioMCP

Conecta assistentes de IA a fontes autoritativas de dados biomédicos como PubMed e ClinicalTrials.gov, permitindo consultas em linguagem natural.

GitHub
597
Experimente este MCPPatrocinado

Documentação

BioMCP

Um binário. Uma gramática. Evidências das fontes biomédicas em que você já confia.

O que é o BioMCP?

O BioMCP é um binário de CLI com uma única gramática de comandos que alcança cerca de 30 fontes biomédicas confiáveis (PubMed, ClinVar, ClinicalTrials.gov, OncoKB, Reactome e outras). Ele também é um servidor MCP (Model Context Protocol), então as mesmas ferramentas estão disponíveis para agentes de IA como Claude Code, Codex e Claude Desktop.

O BioMCP atravessa o labirinto usual de dados biomédicos: uma única consulta alcança as fontes que normalmente vivem atrás de diferentes APIs, identificadores e hábitos de busca. Pesquisadores, clínicos e agentes usam a mesma gramática de comandos para buscar, focar e mudar de direção sem reconstruir o fluxo de trabalho para cada fonte. Você obtém resultados compactos e orientados a evidências em dados públicos ao vivo, além de análises locais de estudos.

Recursos

  • Busque na literatura: search article se expande pelo PubTator3 e Europe PMC, deduplica identificadores PMID/PMCID/DOI e pode adicionar uma etapa do Semantic Scholar quando seus filtros suportarem.
  • Mude de direção sem retrabalho: vá de um gene, variante, fármaco, doença, via, proteína ou artigo direto para a próxima visão integrada, em vez de reconstruir filtros manualmente.
  • Escolha um manual: biomcp skill list mostra exemplos práticos já enviados para você abrir o fluxo de trabalho biomcp skill <slug> correspondente.
  • Analise estudos localmente: os comandos study cobrem fluxos locais de consulta, coorte, sobrevivência, comparação e co-ocorrência com gráficos nativos em terminal, SVG e PNG para conjuntos de dados baixados no estilo cBioPortal.
  • Siga o rastro do artigo: article citations, article references, article recommendations e article entities transformam um artigo conhecido em um mapa de evidências mais amplo.
  • Enriqueça e processe em lote: use biomcp enrich para enriquecimento de nível superior com g:Profiler e biomcp batch para até 10 chamadas focadas de get em um único comando.

Início rápido

Primeira consulta útil em 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

Instalação

Instalação do binário

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

Instalação da ferramenta PyPI

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

Aviso sobre o pacote PyPI: instale biomcp-cli, não biomcp. O pacote PyPI biomcp não tem relação com este projeto.

Marcador de propriedade do MCP Registry: mcp-name: io.github.genomoncology/biomcp.

Isso instala o binário biomcp em ~/.local/bin. Se esse diretório ainda não estiver no PATH, o instalador imprime um comando para adicioná-lo; ele nunca edita seus arquivos de inicialização do shell.

Homebrew

brew tap genomoncology/biomcp
brew install biomcp

O repositório de tap genomoncology/homebrew-biomcp separado deve existir antes que esses comandos funcionem.

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

Use a imagem GHCR para verificações rápidas de CLI ou clientes MCP stdio sem instalação local.

Plugin do Claude Code

Instale o binário biomcp primeiro, depois adicione o marketplace de plugins hospedado e instale o plugin BioMCP no Claude Code:

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

O plugin conecta o Claude Code ao servidor MCP stdio local com biomcp serve. Para fluxos de trabalho guiados do BioMCP, instale também os assets de habilidades abaixo.

Servidor MCP do Codex

Instale o binário biomcp primeiro e registre o mesmo servidor MCP stdio com o Codex:

codex mcp add biomcp -- biomcp serve

Extensão do Claude Desktop (.mcpb)

Instale o BioMCP pelo Anthropic Directory no Claude Desktop quando esse caminho estiver disponível no seu ambiente. Para configurações locais/manuais, use a configuração JSON MCP abaixo.

Instalar habilidades

Instale fluxos de investigação guiados no diretório do seu agente:

biomcp skill install ~/.claude --force

Clientes MCP

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

Servidor HTTP remoto

Para implantações compartilhadas ou remotas:

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

Clientes remotos se conectam a http://127.0.0.1:8080/mcp. As rotas de sondagem são GET /health, GET /readyz e GET /.

Demonstração executável:

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

Consulte Servidor HTTP Remoto para o guia de iniciantes.

A partir do código-fonte

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

Para verificação local do repositório, execute os portões padrão diretamente: make lint, make test e make spec. make test inclui tanto o Rust nextest quanto a faixa de contrato Python/docs, enquanto make release-gate adiciona a prova nomeada de recursos completos e executa as especificações contra o binário de release com todos os recursos. Não há comando make check suportado. Use make verify apenas para confiança opcional em upstream público ao vivo; make release-live-smoke permanece como um alias de compatibilidade.

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 e fontes

As tabelas abaixo distinguem entidades de cartão de detalhes de superfícies somente de busca, para que agentes não criem comandos get não suportados.

Entidades obtíveis

EntidadeProvedores upstream usados pelo BioMCPExemplo
geneMyGene.info, UniProt, Reactome, QuickGO, STRING, GTEx, Human Protein Atlas, DGIdb, ClinGen, NIH Reporter, DisGeNET, pivô de diagnóstico com suporte GTRbiomcp get gene BRAF pathways hpa
varianteMyVariant.info, ClinVar, dados populacionais diretos do gnomAD v4, CIViC, Cancer Genome Interpreter, OncoKB, cBioPortal, GWAS Catalog, AlphaGenomebiomcp get variant "BRAF V600E" clinvar
artigoPubMed, PubTator3, Europe PMC, PMC OA, NCBI ID Converter, Semantic Scholar (auth opcional; S2_API_KEY recomendado)biomcp search article -g BRAF --limit 5
ensaio clínicoClinicalTrials.gov API v2, NCI CTS APIbiomcp search trial -c melanoma -s recruiting
diagnósticoNCBI Genetic Testing Registry bundle local em massa + CSV local da WHO IVD + overlay opcional de dispositivos OpenFDAbiomcp get diagnostic GTR000006692.3 regulatory
fármacoMyChem.info, bundle local DDInter, lote local EMA, exportações locais da WHO Prequalification, ChEMBL, OpenTargets, Drugs@FDA, rótulos/escassez/aprovações/FAERS/MAUDE/recalls OpenFDA, CIViCbiomcp drug interactions warfarin
doençaMyDisease.info, Monarch Initiative, MONDO, OpenTargets, Reactome, CIViC, SEER Explorer, NIH Reporter, DisGeNET, pivô de diagnóstico GTR/WHO IVDbiomcp get disease "Lynch syndrome" genes
viaReactome, KEGG, WikiPathways, g:Profiler, seções de enriquecimento com suporte Enrichrbiomcp get pathway hsa05200 genes
proteínaUniProt, InterPro, STRING, ComplexPortal, PDB, AlphaFoldbiomcp get protein P15056 complexes
evento adversoOpenFDA FAERS/MAUDE/recalls mais busca agregada de vacinas CDC WONDER VAERSbiomcp search adverse-event --drug pembrolizumab
pgxCPIC, PharmGKBbiomcp get pgx CYP2D6 recommendations

Entidades somente de busca

EntidadeProvedores upstream usados pelo BioMCPExemplo
gwasGWAS Catalogbiomcp search gwas --trait "type 2 diabetes"
fenótipoMonarch Initiative (similaridade semântica HPO)biomcp search phenotype "HP:0001250"

Auxiliares entre entidades

Mude entre entidades relacionadas sem reconstruir filtros.

Consulte o guia de pivô entre entidades para saber quando usar um auxiliar versus uma nova busca.

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

Enriquecimento de conjuntos de genes

biomcp enrich BRAF,KRAS,NRAS --limit 10

O biomcp enrich de nível superior usa g:Profiler. Seções de enriquecimento de genes dentro de outras visões de entidade ainda referenciam Enrichr quando essa é a fonte de apoio.

Seções e divulgação progressiva

Todo comando get suporta seções selecionáveis para saída focada:

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

No modo JSON, as respostas get expõem _meta.next_commands para os próximos acompanhamentos prováveis e _meta.section_sources para proveniência no nível da seção. batch ... --json retorna objetos por entidade com o mesmo formato de metadados.

Chaves de API

A maioria dos comandos funciona sem credenciais. Chaves opcionais melhoram limites de taxa ou desbloqueiam enriquecimentos opcionais:

export NCBI_API_KEY="..."        # 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, article batch, get article ... tldr e os auxiliares explícitos do Semantic Scholar funcionam todos sem S2_API_KEY. Com a chave, o BioMCP envia solicitações autenticadas e usa um limite de taxa dedicado de 1 req/seg. Sem ela, o BioMCP usa o pool compartilhado não autenticado de 1 req/2 seg. search article --source suporta all, pubtator, europepmc, pubmed, semanticscholar e litsense2. A federação de artigos compatível padrão usa PubTator3, Europe PMC, PubMed e Semantic Scholar automático; use --source semanticscholar ou --source litsense2 explicitamente quando quiser apenas uma dessas fontes. A seleção explícita de fonte também desativa o enriquecimento de linhas entre provedores. Referências e recomendações podem ficar vazias para artigos com paywall por causa da elisão do editor na cobertura upstream do Semantic Scholar.

Configuração

Configurações da extensão do Claude Desktop

O bundle de diretório expõe apenas as configurações opcionais necessárias para o primeiro build voltado a revisores:

Campo do Claude DesktopVariável de ambiente em runtimeFinalidade
OncoKB TokenONCOKB_TOKENHabilita evidências de terapia e nível biomcp variant oncokb "<gene> <variant>"
DisGeNET API KeyDISGENET_API_KEYHabilita seções DisGeNET com pontuação em consultas de gene e doença
Semantic Scholar API KeyS2_API_KEYMelhora a confiabilidade dos auxiliares de TLDR, citação, referência e recomendação de artigos

O primeiro build de diretório expõe apenas essas três configurações opcionais. Variáveis de ambiente avançadas somente CLI permanecem documentadas em Chaves de API para o caminho geral da CLI do BioMCP.

Exemplos de uso

Visão geral pública entre entidades

Prompt do usuário: Dê-me uma visão geral de baixo ruído do BRAF no melanoma.

Chamada de ferramenta esperada: biomcp search all --gene BRAF --disease melanoma --counts-only

Comportamento esperado: Retorna um resumo de contagens entre entidades que orienta o próximo comando em vez de despejar tabelas longas de detalhes.

Saída esperada: Resumo com contagens primeiro e comandos sugeridos para os acompanhamentos de entidade de maior rendimento.

Evidência pública de variante

Prompt do usuário: Resuma a significância do ClinVar e a frequência populacional para BRAF V600E.

Chamada de ferramenta esperada: biomcp get variant "BRAF V600E" clinvar population

Comportamento esperado: Recupera o cartão de variante focado, a seção ClinVar e os dados de frequência populacional em uma única chamada somente leitura.

Saída esperada: Resumo da variante, detalhes de significância do ClinVar e frequências populacionais do gnomAD.

Exemplo OncoKB com credenciais

Prompt do usuário: Mostre evidências de terapia OncoKB para BRAF V600E.

Chamada de ferramenta esperada: biomcp variant oncokb "BRAF V600E"

Comportamento esperado: Usa ONCOKB_TOKEN quando configurado e, caso contrário, retorna orientação útil sobre a credencial ausente.

Saída esperada: Evidências de terapia e nível quando ONCOKB_TOKEN estiver definido, ou uma dica clara de configuração quando não estiver.

Exemplo DisGeNET com credenciais

Prompt do usuário: Mostre associações DisGeNET com pontuação para TP53.

Chamada de ferramenta esperada: biomcp get gene TP53 disgenet

Comportamento esperado: Usa DISGENET_API_KEY para recuperar a seção de associação gene-doença com pontuação.

Saída esperada: Tabela de associações de doenças classificadas com contagens de evidências e pontuações quando DISGENET_API_KEY estiver configurado.

Política de privacidade

O BioMCP não adiciona telemetria, análises ou upload de logs remotos. Revise a declaração completa de privacidade em https://biomcp.org/policies/.

Implantação multiworker

A limitação de taxa do BioMCP é local ao processo. Para muitos workers concorrentes, execute um endpoint compartilhado Streamable HTTP biomcp serve-http para que todos os workers compartilhem um único orçamento de limitador:

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

Servidores loopback aceitam apenas valores Host locais por padrão. Um bind não loopback exige --allowed-hosts. A saída de emergência explícita --unsafe-allow-any-host desativa apenas essa verificação de Host; ela não adiciona autenticação, TLS ou criptografia. Coloque implantações remotas atrás de um proxy TLS autenticado confiável ou dentro de uma rede privada.

Clientes remotos devem se conectar a http://<host>:8080/mcp. Sondas de processo leves estão disponíveis em GET /health, GET /readyz e GET /.

Habilidades

O BioMCP inclui um guia de agente embutido e um catálogo de exemplos práticos. Use biomcp skill list quando precisar do exemplo prático certo e depois use biomcp skill para ler o guia BioMCP embutido ou instalá-lo no diretório do seu agente quando quiser cópias locais das referências de fluxo de trabalho:

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

Consulte Habilidades para alvos de instalação suportados, arquivos instalados e notas de compatibilidade legadas.

Análises locais de estudos

study é a família de análise local do BioMCP para conjuntos de dados baixados no estilo cBioPortal. A superfície de entidades públicas lida com descoberta/detalhe baseado em API, runtime local e híbrido; os comandos study funcionam em conjuntos de dados locais quando você precisa de consulta por estudo, coorte, sobrevivência, comparação ou fluxos de trabalho de co-ocorrência. Consultas por gene incluem mutações, CNA, expressão e variantes estruturais/fusões de arquivos data_sv.txt locais. Os resumos de mutação permanecem apenas com mutações e observam quando fusões/SV precisam de --type sv.

Use study download para buscar um conjunto de dados na raiz do seu estudo local. Defina BIOMCP_STUDY_DIR quando quiser um local explícito para o conjunto de dados para scripts e demonstrações reproduzíveis; se não estiver definido, o BioMCP usa a raiz de estudo padrão.

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 a referência da CLI para a família completa de comandos study e pré-requisitos de conjuntos de dados.

Operações

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

Suporte

Documentação

Citação

Se você usar o BioMCP em pesquisas, cite-o via CITATION.cff. O GitHub também expõe Cite this repository na barra lateral do repositório quando esse arquivo está presente.

Fontes de Dados e Licenciamento

O BioMCP é licenciado sob MIT. Ele realiza consultas sob demanda contra provedores upstream em vez de revender ou espelhar seus conjuntos de dados, mas os termos upstream regem a reutilização dos resultados obtidos.

Alguns provedores são totalmente abertos, alguns recursos do BioMCP exigem registro ou chaves de API, e algumas fontes consultáveis ainda impõem limites notáveis de reutilização. As duas maiores ressalvas são KEGG, que distingue uso acadêmico e não acadêmico, e COSMIC, que o BioMCP mantém apenas indireto porque seu modelo de licenciamento é incompatível com uma integração aberta direta.

Use Licenciamento e Termos de Fontes para o detalhamento por fonte e Chaves de API para etapas de configuração e links de registro.

Licença

MIT