PubChem MCP Server

---

Descripción general

Datos de compuestos químicos y bioensayos de las API PUG REST y PUG View de PubChem. Busca compuestos por identificador, fórmula o estructura; obtén propiedades fisicoquímicas, datos de seguridad, bioactividad, interacciones, referencias cruzadas y estructuras 3D; encuentra bioensayos por objetivo biológico. Se ejecuta como un proceso stdio, un servidor HTTP Streamable local o el endpoint público alojado anterior.

Herramientas

Herramienta	Descripción
pubchem_search_compounds	Busca compuestos por nombre, SMILES, InChIKey, fórmula, subestructura, superestructura o similitud 2D.
pubchem_get_compound_details	Obtén propiedades fisicoquímicas, descripciones, sinónimos, similitud con fármacos y clasificación de compuestos por CID.
pubchem_get_compound_image	Obtén un diagrama de estructura 2D (PNG) para un compuesto por CID.
pubchem_get_compound_3d_structure	Obtén un conformador 3D (coordenadas atómicas y enlaces) para un compuesto por CID, como JSON analizado o SDF sin procesar.
pubchem_get_compound_xrefs	Obtén referencias cruzadas de bases de datos externas (PubMed, patentes, genes, proteínas, etc.).
pubchem_get_compound_safety	Obtén clasificación de peligro GHS y datos de seguridad para uno o más compuestos por CID (lote).
pubchem_get_bioactivity	Obtén el perfil de bioactividad de un compuesto: resultados de ensayos, objetivos y valores de actividad; filtra por resultado o objetivo molecular.
pubchem_get_compound_interactions	Obtén interacciones fármaco-fármaco, fármaco-alimento y químico-objetivo para un compuesto por CID.
pubchem_search_assays	Encuentra bioensayos por objetivo biológico (símbolo de gen, proteína, ID de gen, acceso UniProt).
pubchem_get_summary	Obtén resúmenes de entidades de PubChem: ensayos, genes, proteínas, taxonomía.

Recursos

Los registros de compuestos y ensayos también se exponen como recursos con plantilla de URI, respaldados por los mismos métodos de cliente que las herramientas; muchos clientes MCP son solo de herramientas y nunca muestran recursos.

Recurso	Descripción
pubchem://compound/{cid}	Propiedades fisicoquímicas principales (JSON).
pubchem://compound/{cid}/safety	Clasificación de peligro GHS (JSON).
pubchem://compound/{cid}/image	Diagrama de estructura 2D (PNG).
pubchem://compound/{cid}/xrefs	Referencias cruzadas externas (JSON).
pubchem://compound/{cid}/bioactivity	Perfil de actividad de bioensayo (JSON).
pubchem://assay/{aid}	Resumen de BioAssay (JSON).

Referencia de capacidades

pubchem_search_compounds _herramienta

• Cinco estrategias de búsqueda: identificador (nombre/SMILES/InChIKey, lote de 1-25), fórmula (notación de Hill, allowOtherElements opcional), contención de subestructura/superestructura o similitud Tanimoto 2D (umbral 70-100, predeterminado 90)
• Cada estrategia necesita sus propios campos — identificador: identifierType + identifiers; fórmula: formula; subestructura/superestructura/similitud: query + queryType — y uno faltante o vacío se rechaza antes de la llamada ascendente
• Limita a 200 CIDs por página (predeterminado 20); offset pagina hasta un máximo de 10,000 — las búsquedas por identificador resuelven cada coincidencia de antemano, por lo que la paginación es gratuita, mientras que las búsquedas por fórmula/estructura/similitud cuestan más ascendente por página profunda
• La hidratación opcional properties evita una llamada de seguimiento a pubchem_get_compound_details
• El modo identificador informa unresolvedIdentifiers para entradas que no resolvieron a ningún CID — sin coincidencia en PubChem, o un SMILES que PubChem no puede interpretar — mientras que el resto del lote aún se resuelve, además de avisos cuando múltiples entradas coinciden en un solo CID
• Una consulta que PubChem no puede buscar (SMILES o fórmula malformados, un átomo comodín *, un CID sin registro) falla rápidamente con una pista search_query_rejected que indica qué corregir
• Informa un totalFound exacto cuando se observó el conjunto completo de coincidencias, o un piso totalFoundAtLeast cuando una búsqueda ascendente limitada se saturó

---

pubchem_get_compound_details _herramienta

• Hasta 100 CIDs por llamada; 27 propiedades disponibles, con un conjunto principal predeterminado de 14 (fórmula, peso, nombre IUPAC, formas SMILES, InChIKey, XLogP, TPSA, recuentos de enlaces H/enlaces rotables, recuento de átomos pesados, carga, complejidad)
• Descripciones textuales opcionales, paginadas mediante descriptionOffset/maxDescriptions (predeterminado 3, hasta 20) — obtenidas solo para los primeros 10 CIDs del lote, los CIDs restantes se enumeran en skippedCids
• Sinónimos opcionales para cada CID encontrado, paginados mediante synonymOffset/maxSynonyms (predeterminado 20, hasta 100)
• Evaluación opcional de similitud con fármacos (Regla de los Cinco de Lipinski + reglas de Veber), calculada a partir de las propiedades devueltas sin latencia adicional
• Clasificación farmacológica opcional (clases/mecanismos de la FDA, clases MeSH, códigos ATC) — mismo límite de expansión de 10 CIDs que las descripciones
• found: false por CID distingue un CID inexistente de un compuesto real del que PubChem simplemente no tiene datos

---

pubchem_get_compound_image _herramienta

• CID único; size es "small" (100x100) o "large" (300x300, predeterminado)
• Devuelve PNG codificado en base64 más ancho/alto
• Error tipado cid_not_found cuando PubChem no tiene registro para el CID

---

pubchem_get_compound_3d_structure _herramienta

• CID único; format="json" (predeterminado) devuelve átomos analizados (elemento + x/y/z) y enlaces, format="sdf" devuelve el texto SDF V2000 sin procesar
• maxAtoms/maxBonds limitan la vista previa JSON (predeterminado 200 cada uno); atomCount/bondCount siempre informan los totales completos, con cualquier limitación revelada mediante enriquecimiento
• includeRawSdf omite el límite predeterminado de 500 líneas en el texto SDF sin procesar
• includeAlternateConformerIds opcional enumera IDs de conformadores más allá del predeterminado
• Error tipado no_3d_structure cuando PubChem no tiene coordenadas 3D calculadas (moléculas grandes, mezclas, algunas sales)

---

pubchem_get_compound_xrefs _herramienta

• CID único; uno o más xrefTypes — IDs de cadena (RegistryID, RN para números CAS, PatentID) e IDs numéricos (PubMedID, GeneID, ProteinGI, TaxonomyID)
• Paginado por tipo: maxPerType hasta 500 (predeterminado 50), con el mismo offset aplicado a cada tipo solicitado
• Cada tipo informa su propio totalAvailable y bandera truncated
• El aviso de resultado vacío distingue "este compuesto no tiene ninguno de los tipos solicitados" de un CID posiblemente mal escrito

---

pubchem_get_compound_safety _herramienta

• Lote de 1-25 CIDs
• Devuelve palabra de señal GHS, pictogramas, declaraciones de peligro (códigos H) y declaraciones de precaución (códigos P), con atribución de fuente
• status por CID: ok, no_ghs_data (el compuesto existe, sin clasificación depositada) o cid_not_found (sin registro en PubChem en absoluto) — se mantienen distintos para que un CID incorrecto nunca se lea como "sin peligros en el archivo"
• Las declaraciones de precaución llevan una bandera decoded — falso para códigos que necesitan texto de relleno específico de etiqueta o fuera de la tabla del decodificador; el código en sí sigue siendo autoritativo

---

pubchem_get_bioactivity _herramienta

• CID único; filtra por outcomeFilter (active/inactive/all, predeterminado all) y/o targetGeneId/targetAccession
• Limita a 100 resultados por página (predeterminado 20); offset alcanza el resto
• Informa totalAssays/activeCount/inactiveCount para todo el compuesto, más filteredCount/returnedCount para la página actual
• Los avisos distinguen "sin datos de bioactividad en absoluto" de "el filtro excluyó todo" de "desplazamiento más allá del final"

---

pubchem_get_compound_interactions _herramienta

• CID único; uno o más kinds — drug-drug (DrugBank), drug-food, target (unión/actividad de BindingDB, ChEMBL y otros); predeterminado ["drug-drug"]
• maxEntries por tipo por página (1-50, predeterminado 10); offset cuenta registros de fuente en lugar de entradas devueltas, limitado a 2,147,483,646
• Cada tipo pagina de forma independiente — paging[] informa totalRecords/nextOffset/truncated por tipo; el nextOffset de nivel superior se completa solo cuando exactamente un tipo solicitado aún tiene registros restantes
• Un tipo que falla al recuperar se nombra en failedKinds sin fallar los tipos que tuvieron éxito

---

pubchem_search_assays _herramienta

• Busca por targetType: genesymbol/proteinname (texto), geneid (ID de gen NCBI), proteinaccession (UniProt)
• Limita a 200 AIDs por página (predeterminado 50); offset pagina hasta el total encontrado
• Rechaza un targetQuery vacío y una consulta geneid no numérica antes de la llamada ascendente
• Informa totalFound en todas las páginas y distingue "sin coincidencia" de "desplazamiento más allá del final"

---

pubchem_get_summary _herramienta

• entityType: assay (AID), gene (ID de gen NCBI), protein (acceso UniProt) o taxonomy (ID de Tax); hasta 10 identificadores por llamada
• Bandera found por identificador; los campos poblados dependen de entityType (la taxonomía incluye un lineage ordenado, el gen incluye symbol/taxonomy)
• El aviso informa cuántos identificadores no se encontraron y qué tipo de ID espera entityType

---

pubchem://compound/{cid} _recurso

• Propiedades fisicoquímicas principales (el mismo conjunto predeterminado de 14 propiedades que pubchem_get_compound_details), como application/json
• Lanza un error tipado de no encontrado cuando el CID no existe en PubChem
• Usa pubchem_get_compound_details para seleccionar propiedades específicas o agregar descripciones, sinónimos, similitud con fármacos y clasificación

---

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

• Clasificación de peligro GHS como application/json
• status (ok/no_ghs_data/cid_not_found) es la única señal que distingue un CID incorrecto de un compuesto sin clasificación depositada — una lectura de recurso no tiene superficie de aviso

---

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

• Diagrama de estructura 2D, PNG 300x300, devuelto como blob base64
• Usa pubchem_get_compound_image para la opción de tamaño 100x100

---

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

• Conjunto predeterminado enfocado — RN (CAS), RegistryID, PubMedID — hasta 25 IDs por tipo, como application/json
• Usa pubchem_get_compound_xrefs para el conjunto completo de tipos de xref, un límite por tipo más alto y paginación con desplazamiento

---

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

• Hasta 25 ensayos como application/json, más totalAssays/activeCount para todo el compuesto
• Usa pubchem_get_bioactivity para filtrar por resultado u objetivo, aumentar el límite o paginar con desplazamiento

---

pubchem://assay/{aid} _recurso

• Resumen de BioAssay como application/json — nombre, descripción, fuente, protocolo, recuentos de sustancias
• Lanza un error tipado de no encontrado cuando el AID no existe

Características

Construido sobre @cyanheads/mcp-ts-core: transportes stdio y Streamable HTTP, autenticación conectable (none / jwt / oauth), almacenamiento intercambiable (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), registro estructurado con rastreo opcional de OpenTelemetry.

Específico de PubChem:

• Cubre tanto los endpoints de PUG REST (búsqueda, propiedades, referencias cruzadas, seguridad, bioactividad, interacciones) como los de PUG View (descripciones textuales, clasificación farmacológica)
• Cliente con límite de velocidad (5 solicitudes/seg) con cola automática de solicitudes, y reintento con retroceso exponencial en errores 5xx y fallos de red
• Una llamada a herramienta o lectura de recurso cancelada detiene su trabajo de PubChem — solicitudes en cola, búsquedas en curso, retrocesos de reintento y sondeo de búsqueda asíncrona — y falla con RequestCancelled
• Analizador SDF V2000 hecho a mano para átomos y enlaces de conformeros 3D; drug-likeness (Lipinski/Veber) calculado a partir de propiedades ya obtenidas, sin añadir latencia extra
• Todas las herramientas son de solo lectura e idempotentes — no se requieren claves API, la API de PubChem es de acceso libre

Salida amigable para agentes:

• Contratos de salida discriminados — por-CID status (ok / no_ghs_data / cid_not_found) y banderas found permiten a los llamadores ramificar según los datos en lugar de comparar una cadena de error
• Fallo parcial elegante — las herramientas por lotes devuelven resultados por elemento junto con unresolvedIdentifiers, skippedCids y failedKinds en lugar de fallar toda la llamada
• Modelado de respuesta — divulgación de truncamiento (truncated, shown/cap, nextOffset) en cada lista limitada, más un piso de totalFoundAtLeast en lugar de un recuento cuando una búsqueda ascendente se satura
• Razones de error tipadas — los fallos de validación y no encontrado declaran un reason (p. ej. cid_not_found, missing_identifier_args, invalid_cid_query) con texto de recuperación accionable, no mensajes genéricos

Primeros pasos

Instancia pública alojada

Hay una instancia pública disponible en https://pubchem.caseyjhand.com/mcp — no requiere instalación. Apunte cualquier cliente MCP hacia ella mediante Streamable HTTP:

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

Autoalojado / Local

Añada lo siguiente a su archivo de configuración del cliente MCP.

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

O con npx (sin necesidad de Bun):

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

O con 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, configure el transporte e inicie el servidor:

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

Requisitos previos

• Bun v1.4.0 o superior (o Node.js v24+).
• No se requieren claves API — la API de PubChem es de acceso libre.

Instalación

1. Clone el repositorio:

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

2. Navegue al directorio:

cd pubchem-mcp-server

3. Instale las dependencias:

bun install

4. Configure el entorno (opcional):

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

Configuración

Variable	Descripción	Predeterminado
MCP_TRANSPORT_TYPE	Transporte: stdio o http.	stdio
MCP_HTTP_PORT	Puerto para el servidor HTTP.	3010
MCP_HTTP_HOST	Host para el servidor HTTP.	127.0.0.1
MCP_SESSION_MODE	stateless, stateful o auto. PubChem no necesita entrada de múltiples rondas, por lo que el servidor declara stateless; el ejemplo y Docker lo configuran para que coincida.	stateless
MCP_AUTH_MODE	Modo de autenticación: none, jwt o oauth.	none
MCP_LOG_LEVEL	Nivel de registro (RFC 5424).	info
STORAGE_PROVIDER_TYPE	Backend de almacenamiento.	in-memory
OTEL_ENABLED	Habilitar OpenTelemetry.	false

Consulte .env.example para la lista completa de anulaciones opcionales.

Ejecución del servidor

Desarrollo local

• Compilar y ejecutar:

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

• Ejecutar comprobaciones y pruebas:

  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

El Dockerfile usa por defecto transporte HTTP, modo de sesión sin estado y registra en /var/log/pubchem-mcp-server. Las dependencias opcionales de OpenTelemetry se instalan por defecto — compile con --build-arg OTEL_ENABLED=false para omitirlas.

Estructura del proyecto

Directorio	Propósito
src/index.ts	Punto de entrada de createApp() — registra herramientas/recursos e inicializa el cliente de PubChem.
src/mcp-server/tools/definitions/	Definiciones de herramientas (*.tool.ts).
src/mcp-server/resources/definitions/	Definiciones de recursos (*.resource.ts).
src/services/pubchem/	Cliente de API de PubChem — límite de velocidad, reintento y análisis de respuesta/SDF.
scripts/	Scripts de compilación, limpieza, devcheck y generación de árboles.
tests/	Pruebas unitarias y de integración.

Guía de desarrollo

Consulte CLAUDE.md para las pautas de desarrollo y reglas arquitectónicas. La versión corta:

• Los manejadores lanzan excepciones, el marco las captura — sin try/catch en la lógica de herramientas
• Use ctx.log para registro con ámbito de solicitud
• Envuelva las llamadas a API externas: valide la respuesta cruda de PubChem → normalice a un tipo de dominio → devuelva el esquema de salida; nunca invente campos faltantes
• Registre nuevas herramientas y recursos en los archivos barrel de index.ts

Contribuciones

Las incidencias son bienvenidas. Ejecute las comprobaciones antes de enviar:

bun run devcheck
bun run test

Licencia

Apache-2.0 — consulte LICENSE para más detalles.