Genomics MCP

Genomics MCP

Deixe seu assistente de IA recuperar dados genômicos reais e evidências de referência, com as fontes de onde vieram.

Genomics MCP é um servidor local de Model Context Protocol. Um agente pode usá-lo para encontrar conjuntos de dados públicos e ler uma região limitada de arquivos de arquivo, remotos ou locais. Ele também pode consultar variantes e genes em bancos de dados de referência públicos. Consultas de região usam uma montagem explícita e coordenadas half-open de base 0. Quando o formato e o servidor suportam leituras de intervalo, uma região é lida sem baixar o arquivo inteiro. Downloads de arquivos inteiros são uma etapa separada e orçada. Os resultados relatam quais fontes foram consultadas (procedência e status por fonte), com acessões, versões e horários de recuperação quando a fonte os fornece.

É uma ferramenta de pesquisa. Ela recupera e relata dados. Não fornece interpretação clínica, não chama variantes nem tira conclusões biológicas.

Para quem é

Biólogos computacionais e pesquisadores que desejam que um agente obtenha dados de EGA, ENA, ENCODE, GEO, NCBI ou de seus próprios arquivos indexados sem escrever código de integração. Também atende pessoas que constroem agentes ou avaliações e precisam de dados reais com fontes rastreáveis. Ela não gera benchmarks por conta própria.

Exemplos de solicitações

Prompts ilustrativos; os resultados dependem do seu cliente e modelo. Intervalos são half-open de base 0 (início incluído, fim excluído); posições de variantes no estilo VCF são de base 1.

• "Mostre as leituras do arquivo EGA EGAF00007243773 (conjunto de dados EGAD00001003338) sobrepostas a GRCh38 chr10:[10000, 10050)." Precisa de GENOMICS_MCP_EGA_PUBLIC_TEST_ACCOUNT=1, a conta de teste pública documentada da EGA.
• "Qual é o sinal médio do arquivo ENCODE ENCFF792QDS sobre GRCh38 chr1:[1000000, 1001000)?"
• "Verifique a base de referência da variante GRCh38 7-140753336-A-T contra o NCBI e depois liste seus registros ClinVar com classificações germinativas, somáticas e de oncogenicidade mantidas separadas."
• "Baixe o FASTA da ENA para DQ285577.1 e mostre suas primeiras 30 bases."
• "Compare genótipos em chr1:[100000, 200000) entre os dois VCFs na minha pasta de dados."

Exemplo medido

A solicitação ENCODE acima, executada em uma instalação limpa em 2026-09-25 com dados ao vivo:

• Arquivo: ENCODE ENCFF792QDS, GRCh38 bigWig, 1.413.106.336 bytes
• Intervalo: chr1:[1000000, 1001000)
• Resultado: média exata 26.361254017233847, a partir de leituras de intervalo HTTP. O workspace ficou com 0 bytes depois (nada foi gravado em disco; leituras de rede ainda ocorreram).

Quatro outras demonstrações ao vivo foram executadas com a mesma instalação: uma região de BAM de teste da EGA, um download de sequência da ENA, uma verificação de referência com ClinVar e MinIO local. Comandos e resultados legíveis por máquina: docs/demos.md.

Estudo de caso de agente: um agente Claude Code, limitado às ferramentas deste servidor, compara o sinal de DNase-seq da ENCODE no enhancer eritroide BCL11A em 26 arquivos, com uma transcrição e uma reprodução sem modelo: examples/agent-case-study/.

Início rápido

Contêiner (Linux x86_64 com Docker)

A imagem é linux/amd64. Ela é testada em Linux x86_64; Docker no macOS não é testado. Crie a pasta de dados primeiro; ela é montada somente leitura.

{
  "mcpServers": {
    "genomics": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--mount", "type=bind,source=/path/to/your/data,target=/data,readonly",
        "--mount", "type=volume,source=genomics-mcp-work,target=/work",
        "ghcr.io/rewire-bio/genomics-mcp:0.1.0"
      ]
    }
  }
}

A partir do código-fonte (macOS arm64, Linux x86_64)

Requer Python 3.12, uv, um compilador C e arquivos de desenvolvimento libcurl e zlib (pyBigWig é compilado a partir do código-fonte para suporte a arquivos remotos).

git clone https://github.com/rewire-bio/genomics-mcp
cd genomics-mcp && git checkout v0.1.0
uv sync --locked --no-dev
uv run --no-dev genomics-mcp --check-config

{
  "mcpServers": {
    "genomics": {
      "command": "uv",
      "args": ["--directory", "/path/to/genomics-mcp", "run", "--no-dev", "genomics-mcp"],
      "env": { "GENOMICS_MCP_ALLOWED_ROOTS": "/path/to/your/data" }
    }
  }
}

Ainda não há pacote PyPI. Wheel, pacote MCPB Linux, comando uvx fixado, notas de Windows (WSL2) e plataforma: docs/install.md.

Cobertura

Área	Fontes e formatos
Descoberta	EGA, ENA (incl. acessões SRA), ENCODE, GEO, NCBI Datasets: estudos, conjuntos de dados, amostras, fenótipos conforme fornecidos, arquivos
Dados genômicos	BAM/CRAM, VCF/BCF, FASTA, BED/GFF3/GTF, bigWig/bigBed em disco local, HTTPS ou S3; regiões EGA via htsget
Transferências	Downloads orçados, retomáveis e com soma de verificação retornados como caminhos locais
Referência	HGNC, Ensembl, ClinVar, gnomAD, UniProt, Open Targets; AlphaGenome Atlas opcional com sua própria chave

Todas as 23 ferramentas e os recursos

Grupo	Ferramentas
Descoberta	list_sources, search_datasets, describe_dataset, list_files, list_samples, get_sample_metadata
Transferências	fetch_file, get_transfer_status, cancel_transfer
Genômica	get_reads, get_coverage, get_pileup, get_variants, get_sequence, get_features, get_signal
Composição	inspect_locus, compare_samples
Referência	resolve_identifier, normalize_variant, lookup_variant, lookup_gene, lookup_protein

Recursos: genomics://capabilities, genomics://status, genomics://schemas, genomics://schemas/{name}.

Padrões e segurança

• Limites: regiões de 1 Mb, 10.000 registros, respostas de 1 MiB e prazo de 30 s; chamadas podem reduzir esses valores. Transferências são limitadas a 100 MiB, a menos que uma chamada defina um orçamento maior. Truncamento é relatado. Nada é transferido entre montagens.
• Somente local: stdio, ou HTTP Streamable com token bearer em 127.0.0.1. Não há serviço hospedado. Leituras locais são limitadas às pastas que você permite, e arquivos de origem nunca são modificados.
• Credenciais e saída: credenciais AWS ambientais nunca são usadas; S3 privado e EGA exigem configuração explícita. Valores de arquivos não marcados como public vão para APIs externas somente quando uma chamada define allow_external_annotation.
• Cache (não lançado; somente checkout de desenvolvimento, não na v0.1.0): um cache em memória limitado reutiliza intervalos de bytes de arquivos HTTPS públicos marcados como public (revalidado por ETag em cada chamada) e respostas de API públicas. Nunca é usado para solicitações privadas, assinadas ou autenticadas. Desligue com [cache] enabled = false; reiniciar limpa. Detalhes e medições: performance.

Configuração: config.example.toml. Escopo e limites conhecidos: PRD.md. Status de diretório e PyPI: registro de publicação. Detalhes técnicos: acesso a dados, arquivos, referências, composição. Segurança: SECURITY.md.

Desenvolvimento

uv sync --locked
uv run ruff check . && uv run ruff format --check .
uv run pytest

Licença

MIT. Veja LICENSE. Dados de cada fonte estão sujeitos aos termos dessa própria fonte.