PubChem MCP Server

---

Ferramentas

Dez ferramentas para consultar o banco de dados de informações químicas do PubChem:

Nome da Ferramenta	Descrição
pubchem_search_compounds	Pesquise compostos por nome, SMILES, InChIKey, fórmula, subestrutura, superestrutura ou similaridade 2D.
pubchem_get_compound_details	Obtenha propriedades físico-químicas, descrições, sinônimos, drug-likeness e classificação para compostos por CID.
pubchem_get_compound_image	Busque um diagrama de estrutura 2D (PNG) para um composto por CID.
pubchem_get_compound_3d_structure	Busque um confôrmero 3D (coordenadas atômicas e ligações) para um composto por CID, como JSON analisado ou SDF bruto.
pubchem_get_compound_xrefs	Obtenha referências cruzadas de bancos de dados externos (PubMed, patentes, genes, proteínas, etc.).
pubchem_get_compound_safety	Obtenha classificação de perigo GHS e dados de segurança para um ou mais compostos por CID (lote).
pubchem_get_bioactivity	Obtenha o perfil de bioatividade de um composto: resultados de ensaios, alvos e valores de atividade; filtre por resultado ou alvo molecular.
pubchem_get_compound_interactions	Obtenha interações medicamento-medicamento, medicamento-alimento e químico-alvo para um composto por CID.
pubchem_search_assays	Encontre bioensaios por alvo biológico (símbolo do gene, proteína, ID do gene, acesso UniProt).
pubchem_get_summary	Obtenha resumos para entidades PubChem: ensaios, genes, proteínas, taxonomia.

pubchem_search_compounds

Pesquise no PubChem por compostos químicos em cinco modos de busca.

• Consulta por identificador — resolva nomes de compostos, SMILES ou InChIKeys para CIDs (lote de até 25)
• Busca por fórmula — encontre compostos pela fórmula molecular em notação de Hill
• Subestrutura/superestrutura — encontre compostos que contêm ou estão contidos em uma estrutura de consulta
• Similaridade 2D — encontre compostos estruturalmente semelhantes por similaridade de Tanimoto (limiar configurável)
• Limite de 200 CIDs por página; offset pagina mais, até um teto de 10.000. Consultas por identificador paginam sobre o conjunto já resolvido; buscas por fórmula e estrutura ampliam sua solicitação upstream limitada para alcançar uma página, então páginas profundas custam mais upstream
• Opcionalmente, enriqueça os resultados com propriedades para evitar uma chamada de detalhes posterior

---

pubchem_get_compound_details

Obtenha informações detalhadas do composto por CID.

• Lotes de até 100 CIDs em uma única solicitação
• 27 propriedades disponíveis: peso molecular, SMILES, InChIKey, XLogP, TPSA, complexidade, contagens de estereoquímica e mais
• Opcionalmente inclui descrições textuais (farmacologia, mecanismo, uso terapêutico) do PUG View — buscadas para os primeiros 10 CIDs de um lote, com os CIDs ignorados nomeados na resposta
• Opcionalmente inclui sinônimos conhecidos (nomes comerciais, nomes sistemáticos, números de registro)
• Sinônimos e descrições são paginados: synonymOffset e descriptionOffset janela cada composto no lote na mesma posição, alcançando as entradas além de uma página
• Opcionalmente calcula a avaliação de drug-likeness (Regra dos Cinco de Lipinski + regras de Veber) a partir das propriedades buscadas
• Opcionalmente busca classificação farmacológica (classes da FDA, mecanismos de ação, classes MeSH, códigos ATC)

---

pubchem_get_bioactivity

Obtenha o perfil de bioatividade de um composto do PubChem BioAssay.

• Retorna resultados de ensaio (Ativo/Inativo/Inconclusivo), informações de alvo (acessos de proteínas, IDs de genes NCBI) e valores quantitativos (IC50, EC50, Ki)
• Filtre por resultado e/ou um alvo molecular específico (ID do gene NCBI ou acesso de proteína)
• Limite de 100 resultados por página; offset alcança o restante (compostos bem estudados podem ter milhares)

---

pubchem_get_summary

Obtenha resumos descritivos para quatro tipos de entidades PubChem.

• Ensaios (AID), genes (ID do gene), proteínas (acesso UniProt), taxonomia (ID do táxon)
• Até 10 entidades por chamada
• Extração de campos específica por tipo para saída limpa e estruturada

---

pubchem_get_compound_interactions

Obtenha dados de interação de um composto por CID.

• Interações medicamento-medicamento (DrugBank), interações medicamento-alimento e ligação/atividade químico-alvo (BindingDB, ChEMBL e outros)
• Selecione quais tipos de interação buscar e limite as entradas por tipo
• Paginado por tipo: cada um relata seu total de registros de origem e seu próprio nextOffset, e offset alcança os registros além de uma página
• Cada entrada carrega sua fonte de origem — a cobertura é mais rica para medicamentos aprovados

---

pubchem_get_compound_3d_structure

Obtenha o confôrmero 3D padrão de um composto por CID.

• format="json" retorna átomos analisados (elemento + x/y/z) e ligações para raciocínio direto; format="sdf" retorna SDF V2000 bruto para passagem para docking ou renderização
• maxAtoms/maxBonds limitam a pré-visualização de átomos/ligações e includeRawSdf opta por um SDF bruto grande além do limite seguro de linhas; atomCount/bondCount sempre relatam os totais e qualquer limitação é divulgada
• Opcionalmente lista IDs de confôrmeros alternativos
• Retorna um não-encontrado tipado quando o PubChem não possui coordenadas 3D calculadas (moléculas grandes, misturas, alguns sais)

Recursos

Registros de compostos e ensaios também são expostos como recursos MCP com template de URI, apoiados pelos mesmos métodos de cliente das ferramentas:

Modelo de URI	Retorna
pubchem://compound/{cid}	Propriedades físico-químicas principais (JSON).
pubchem://compound/{cid}/safety	Classificação de perigo GHS (JSON).
pubchem://compound/{cid}/image	Diagrama de estrutura 2D (PNG).
pubchem://compound/{cid}/xrefs	Referências cruzadas externas (JSON).
pubchem://compound/{cid}/bioactivity	Perfil de atividade de bioensaio (JSON).
pubchem://assay/{aid}	Resumo do BioAssay (JSON).

Características

Construído sobre @cyanheads/mcp-ts-core:

• Definições declarativas de ferramentas — um arquivo por ferramenta, o framework lida com registro e validação
• Tratamento de erros unificado em todas as ferramentas
• Autenticação plugável (none, jwt, oauth)
• Backends de armazenamento intercambiáveis: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1
• Registro estruturado com rastreamento OpenTelemetry opcional
• Executa localmente (stdio/HTTP) ou containerizado via Docker

Específico do PubChem:

• Cliente com limite de taxa para as APIs PUG REST e PUG View (5 req/s com fila automática)
• Tentativas com backoff exponencial em erros 5xx e falhas de rede
• Todas as ferramentas são somente leitura e idempotentes — nenhuma chave de API é necessária

Começando

Instância Pública Hospedada

Uma instância pública está disponível em https://pubchem.caseyjhand.com/mcp — nenhuma instalação é necessária. Aponte qualquer cliente MCP para ela via Streamable HTTP:

{
  "mcpServers": {
    "pubchem-mcp-server": {
      "type": "streamable-http",
      "url": "https://pubchem.caseyjhand.com/mcp"
    }
  }
}

Auto-hospedado / Local

Adicione à configuração do seu cliente MCP (ex.: claude_desktop_config.json):

{
  "mcpServers": {
    "pubchem-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/pubchem-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    }
  }
}

Pré-requisitos

• Bun v1.3.0 ou superior (ou Node.js v24+)

Instalação

1. Clone o repositório:

git clone https://github.com/cyanheads/pubchem-mcp-server.git

1. Navegue até o diretório:

cd pubchem-mcp-server

1. Instale as dependências:

bun install

Configuração

Nenhuma chave de API é necessária — a API do PubChem é de acesso livre.

Variável	Descrição	Padrão
MCP_TRANSPORT_TYPE	Transporte: stdio ou http.	stdio
MCP_HTTP_PORT	Porta para o servidor HTTP.	3010
MCP_HTTP_HOST	Host para o servidor HTTP.	localhost
MCP_AUTH_MODE	Modo de autenticação: none, jwt ou oauth.	none
MCP_LOG_LEVEL	Nível de log (RFC 5424).	info
STORAGE_PROVIDER_TYPE	Backend de armazenamento.	in-memory
OTEL_ENABLED	Habilitar OpenTelemetry.	false

Executando o Servidor

Desenvolvimento Local

• Compilar e executar:

  bun run rebuild
  bun run start:stdio   # or start:http
  

• Executar verificações e testes:

  bun run devcheck     # Lints, formats, type-checks
  bun run test         # Runs test suite
  

Docker

docker build -t pubchem-mcp-server .
docker run -p 3010:3010 pubchem-mcp-server

Estrutura do Projeto

Diretório	Finalidade
src/mcp-server/tools/definitions/	Definições de ferramentas (*.tool.ts).
src/services/pubchem/	Cliente da API PubChem com limite de taxa e análise de resposta.
scripts/	Scripts de compilação, limpeza, devcheck e geração de árvore.

Guia de Desenvolvimento

Veja CLAUDE.md para diretrizes de desenvolvimento e regras arquiteturais. A versão resumida:

• Handlers lançam, o framework captura — sem try/catch na lógica da ferramenta
• Use ctx.log para registro específico de domínio
• Registre novas ferramentas no arquivo barrel index.ts

Contribuindo

Issues e pull requests são bem-vindos. Execute verificações antes de enviar:

bun run devcheck
bun run test

Licença

Apache-2.0 — veja LICENSE para detalhes.