PubChem MCP Server

---

Visão Geral

Dados de compostos químicos e bioensaios das APIs PUG REST e PUG View do PubChem. Pesquise compostos por identificador, fórmula ou estrutura; obtenha propriedades físico-químicas, dados de segurança, bioatividade, interações, referências cruzadas e estruturas 3D; encontre bioensaios por alvo biológico. Funciona como um processo stdio, um servidor Streamable HTTP local ou o endpoint hospedado público acima.

Ferramentas

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 de 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 do PubChem: ensaios, genes, proteínas, taxonomia.

Recursos

Registros de compostos e ensaios também são expostos como recursos com template de URI, apoiados pelos mesmos métodos de cliente das ferramentas; muitos clientes MCP são apenas de ferramentas e nunca exibem recursos.

Recurso	Descrição
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 BioEnsaio (JSON).

Referência de Capacidades

pubchem_search_compounds _ferramenta

• Cinco estratégias de pesquisa: identificador (nome/SMILES/InChIKey, em lote de 1-25), fórmula (notação de Hill, allowOtherElements opcional), contenção de subestrutura/superestrutura ou similaridade Tanimoto 2D (limiar 70-100, padrão 90)
• Cada estratégia precisa de seus próprios campos — identificador: identifierType + identifiers; fórmula: formula; subestrutura/superestrutura/similaridade: query + queryType — e um campo ausente ou em branco é rejeitado antes da chamada upstream
• Limita a 200 CIDs por página (padrão 20); offset pagina até um teto de 10.000 — consultas de identificador resolvem cada correspondência antecipadamente, então a paginação é gratuita, enquanto pesquisas por fórmula/estrutura/similaridade custam mais upstream por página profunda
• Hidratação opcional de properties evita uma chamada de acompanhamento de pubchem_get_compound_details
• O modo identificador relata unresolvedIdentifiers para entradas que não resolveram para nenhum CID — sem correspondência no PubChem, ou um SMILES que o PubChem não consegue interpretar — enquanto o restante do lote ainda resolve, além de avisos quando múltiplas entradas colidem em um único CID
• Uma consulta que o PubChem não consegue pesquisar (SMILES ou fórmula malformados, um átomo curinga *, um CID sem registro) falha rapidamente com uma dica search_query_rejected nomeando o que corrigir
• Relata um totalFound exato quando o conjunto completo de correspondências foi observado, ou um piso de totalFoundAtLeast quando uma pesquisa upstream limitada saturou

---

pubchem_get_compound_details _ferramenta

• Até 100 CIDs por chamada; 27 propriedades disponíveis, com padrão de um conjunto principal de 14 (fórmula, peso, nome IUPAC, formas SMILES, InChIKey, XLogP, TPSA, contagens de ligações H/rotacionáveis, contagem de átomos pesados, carga, complexidade)
• Descrições textuais opcionais, paginadas via descriptionOffset/maxDescriptions (padrão 3, até 20) — buscadas apenas para os primeiros 10 CIDs do lote, CIDs restantes listados em skippedCids
• Sinônimos opcionais para cada CID encontrado, paginados via synonymOffset/maxSynonyms (padrão 20, até 100)
• Avaliação opcional de drug-likeness (Regra dos Cinco de Lipinski + regras de Veber), calculada a partir das propriedades retornadas sem latência adicional
• Classificação farmacológica opcional (classes/mecanismos FDA, classes MeSH, códigos ATC) — mesmo limite de fan-out de 10 CIDs que as descrições
• found: false por CID distingue um CID inexistente de um composto real para o qual o PubChem simplesmente não tem dados

---

pubchem_get_compound_image _ferramenta

• CID único; size é "small" (100x100) ou "large" (300x300, padrão)
• Retorna PNG codificado em base64 mais largura/altura
• Erro tipado cid_not_found quando o PubChem não tem registro para o CID

---

pubchem_get_compound_3d_structure _ferramenta

• CID único; format="json" (padrão) retorna átomos analisados (elemento + x/y/z) e ligações, format="sdf" retorna o texto SDF V2000 bruto
• maxAtoms/maxBonds limitam a pré-visualização JSON (padrão 200 cada); atomCount/bondCount sempre relatam os totais completos, com qualquer limitação divulgada via enriquecimento
• includeRawSdf ignora o limite padrão de 500 linhas no texto SDF bruto
• includeAlternateConformerIds opcional lista IDs de confôrmeros além do padrão
• Erro tipado no_3d_structure quando o PubChem não tem coordenadas 3D calculadas (moléculas grandes, misturas, alguns sais)

---

pubchem_get_compound_xrefs _ferramenta

• CID único; um ou mais xrefTypes — IDs de string (RegistryID, RN para números CAS, PatentID) e IDs numéricos (PubMedID, GeneID, ProteinGI, TaxonomyID)
• Paginado por tipo: maxPerType até 500 (padrão 50), com o mesmo offset aplicado em todos os tipos solicitados
• Cada tipo relata seu próprio totalAvailable e flag truncated
• Aviso de resultado vazio distingue "este composto não tem nenhum dos tipos solicitados" de um CID possivelmente digitado errado

---

pubchem_get_compound_safety _ferramenta

• Lote de 1-25 CIDs
• Retorna palavra de sinalização GHS, pictogramas, declarações de perigo (códigos H) e declarações de precaução (códigos P), com atribuição de fonte
• status por CID: ok, no_ghs_data (composto existe, sem classificação depositada) ou cid_not_found (nenhum registro no PubChem) — mantidos distintos para que um CID inválido nunca seja lido como "sem perigos registrados"
• Declarações de precaução carregam uma flag decoded — falso para códigos que precisam de texto de preenchimento específico do rótulo ou fora da tabela do decodificador; o código em si ainda é autoritativo

---

pubchem_get_bioactivity _ferramenta

• CID único; filtre por outcomeFilter (active/inactive/all, padrão all) e/ou targetGeneId/targetAccession
• Limita a 100 resultados por página (padrão 20); offset alcança o restante
• Relata totalAssays/activeCount/inactiveCount para o composto inteiro, além de filteredCount/returnedCount para a página atual
• Avisos distinguem "nenhum dado de bioatividade" de "o filtro excluiu tudo" de "offset além do fim"

---

pubchem_get_compound_interactions _ferramenta

• CID único; um ou mais kinds — drug-drug (DrugBank), drug-food, target (ligação/atividade de BindingDB, ChEMBL e outros); padrão ["drug-drug"]
• maxEntries por tipo por página (1-50, padrão 10); offset conta registros de fonte em vez de entradas retornadas, limitado a 2.147.483.646
• Cada tipo pagina independentemente — paging[] relata totalRecords/nextOffset/truncated por tipo; o nextOffset de nível superior é preenchido apenas quando exatamente um tipo solicitado ainda tem registros restantes
• Um tipo que falha ao recuperar é nomeado em failedKinds sem falhar os tipos que tiveram sucesso

---

pubchem_search_assays _ferramenta

• Pesquise por targetType: genesymbol/proteinname (texto), geneid (ID do Gene NCBI), proteinaccession (UniProt)
• Limita a 200 AIDs por página (padrão 50); offset pagina até o total encontrado
• Rejeita um targetQuery em branco e uma consulta geneid não numérica antes da chamada upstream
• Relata totalFound em todas as páginas e distingue "sem correspondência" de "offset além do fim"

---

pubchem_get_summary _ferramenta

• entityType: assay (AID), gene (ID do Gene NCBI), protein (acesso UniProt) ou taxonomy (ID de Taxonomia); até 10 identificadores por chamada
• Flag found por identificador; campos preenchidos dependem de entityType (taxonomia inclui um lineage ordenado, gene inclui symbol/taxonomy)
• Aviso relata quantos identificadores não foram encontrados e qual tipo de ID entityType espera

---

pubchem://compound/{cid} _recurso

• Propriedades físico-químicas principais (o mesmo conjunto padrão de 14 propriedades de pubchem_get_compound_details), como application/json
• Lança um erro tipado de não encontrado quando o CID não existe no PubChem
• Use pubchem_get_compound_details para selecionar propriedades específicas ou adicionar descrições, sinônimos, drug-likeness e classificação

---

pubchem://compound/{cid}/safety _recurso

• Classificação de perigo GHS como application/json
• status (ok/no_ghs_data/cid_not_found) é o único sinal que distingue um CID inválido de um composto sem classificação depositada — uma leitura de recurso não tem superfície de aviso

---

pubchem://compound/{cid}/image _recurso

• Diagrama de estrutura 2D, PNG 300x300, retornado como blob base64
• Use pubchem_get_compound_image para a opção de tamanho 100x100

---

pubchem://compound/{cid}/xrefs _recurso

• Conjunto padrão focado — RN (CAS), RegistryID, PubMedID — até 25 IDs por tipo, como application/json
• Use pubchem_get_compound_xrefs para o conjunto completo de tipos de xref, um limite maior por tipo e paginação com offset

---

pubchem://compound/{cid}/bioactivity _recurso

• Até 25 ensaios como application/json, além de totalAssays/activeCount para o composto inteiro
• Use pubchem_get_bioactivity para filtrar por resultado ou alvo, aumentar o limite ou paginar com offset

---

pubchem://assay/{aid} _recurso

• Resumo do BioEnsaio como application/json — nome, descrição, fonte, protocolo, contagens de substâncias
• Lança um erro tipado de não encontrado quando o AID não existe

Recursos

Construído sobre @cyanheads/mcp-ts-core: transportes stdio e Streamable HTTP, autenticação plugável (none / jwt / oauth), armazenamento substituível (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), registro estruturado com rastreamento opcional via OpenTelemetry.

Específico do PubChem:

• Cobre tanto os endpoints PUG REST (busca, propriedades, referências cruzadas, segurança, bioatividade, interações) quanto PUG View (descrições textuais, classificação farmacológica)
• Cliente com limite de taxa (5 req/s) com fila automática de solicitações e nova tentativa com backoff exponencial em erros 5xx e falhas de rede
• Uma chamada de ferramenta ou leitura de recurso cancelada interrompe seu trabalho no PubChem — solicitações na fila, buscas em andamento, backoffs de nova tentativa e sondagem de busca assíncrona — e falha com RequestCancelled
• Parser SDF V2000 feito à mão para átomos e ligações de conformadores 3D; drug-likeness (Lipinski/Veber) calculado a partir de propriedades já buscadas, sem latência adicional
• Todas as ferramentas são somente leitura e idempotentes — nenhuma chave de API é necessária, a API do PubChem é de acesso livre

Saída amigável para agentes:

• Contratos de saída discriminados — por CID, os flags status (ok / no_ghs_data / cid_not_found) e found permitem que os chamadores decidam com base nos dados em vez de comparar uma string de erro
• Falha parcial graciosa — ferramentas em lote retornam resultados por item junto com unresolvedIdentifiers, skippedCids e failedKinds em vez de falhar a chamada inteira
• Modelagem de resposta — divulgação de truncamento (truncated, shown/cap, nextOffset) em cada lista limitada, além de um piso de totalFoundAtLeast no lugar de uma contagem quando uma busca upstream satura
• Razões de erro tipadas — falhas de validação e não encontrado declaram um reason (por exemplo, cid_not_found, missing_identifier_args, invalid_cid_query) com texto de recuperação acionável, não mensagens genéricas

Primeiros passos

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 o seguinte ao arquivo de configuração do seu cliente MCP.

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

Ou com npx (sem necessidade de Bun):

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

Ou com Docker:

{
  "mcpServers": {
    "pubchem-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/pubchem-mcp-server:latest"]
    }
  }
}

Para Streamable HTTP, defina o transporte e inicie o servidor:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Pré-requisitos

• Bun v1.4.0 ou superior (ou Node.js v24+).
• Nenhuma chave de API necessária — a API do PubChem é de acesso livre.

Instalação

1. Clone o repositório:

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

2. Navegue até o diretório:

cd pubchem-mcp-server

3. Instale as dependências:

bun install

4. Configure o ambiente (opcional):

cp .env.example .env
# edit .env to override transport, session mode, storage, or logging defaults

Configuração

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.	127.0.0.1
MCP_SESSION_MODE	stateless, stateful ou auto. O PubChem não precisa de entrada com múltiplas idas e voltas, então o servidor declara stateless; o exemplo e o Docker o definem para corresponder.	stateless
MCP_AUTH_MODE	Modo de autenticação: none, jwt ou oauth.	none
MCP_LOG_LEVEL	Nível de registro (RFC 5424).	info
STORAGE_PROVIDER_TYPE	Backend de armazenamento.	in-memory
OTEL_ENABLED	Habilitar OpenTelemetry.	false

Consulte .env.example para a lista completa de substituições opcionais.

Executando o servidor

Desenvolvimento local

• Compilar e executar:

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• Executar verificações e testes:

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

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

O Dockerfile usa como padrão transporte HTTP, modo de sessão sem estado e registra em /var/log/pubchem-mcp-server. Dependências pares do OpenTelemetry são instaladas por padrão — compile com --build-arg OTEL_ENABLED=false para omiti-las.

Estrutura do projeto

Diretório	Propósito
src/index.ts	Ponto de entrada createApp() — registra ferramentas/recursos e inicializa o cliente PubChem.
src/mcp-server/tools/definitions/	Definições de ferramentas (*.tool.ts).
src/mcp-server/resources/definitions/	Definições de recursos (*.resource.ts).
src/services/pubchem/	Cliente da API PubChem — limite de taxa, nova tentativa e análise de resposta/SDF.
scripts/	Scripts de compilação, limpeza, devcheck e geração de árvore.
tests/	Testes unitários e de integração.

Guia de desenvolvimento

Consulte 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 de ferramentas
• Use ctx.log para registro com escopo de solicitação
• Encapsule chamadas de API externas: valide a resposta bruta do PubChem → normalize para um tipo de domínio → retorne o esquema de saída; nunca invente campos ausentes
• Registre novas ferramentas e recursos nos arquivos barrel index.ts

Contribuindo

Issues são bem-vindas. Execute as verificações antes de enviar:

bun run devcheck
bun run test

Licença

Apache-2.0 — consulte LICENSE para detalhes.