PDBe MCP Servers

Servidores MCP de PDBe (oficiales) del equipo PDBe integran los recursos del Protein Data Bank Europe con LLMs a través del Model Context Protocol. Proporcionan acceso fluido a datos de estructura de proteínas mediante herramientas API y asistencia con esquemas de bases de datos gráficas para la generación inteligente de consultas Cypher, conectando la biología estructural con la investigación en IA.

GitHub

Prueba este MCPPatrocinado

Documentación

Servidores MCP de PDBe

Un conjunto de servidores de Protocolo de Contexto de Modelo (MCP) que proporcionan acceso fluido a la API del Banco de Datos de Proteínas en Europa (PDBe) y a la Búsqueda PDBe. Estos servidores exponen los datos completos de biología estructural de PDBe como herramientas MCP, lo que permite la integración directa con cualquier cliente de IA que admita MCP.

El paquete también incluye un servidor avanzado de Gráfico PDBe para usuarios que ejecutan su propia base de datos de gráficos local PDBe-KB Neo4j. PDBe no proporciona una instancia pública de base de datos de gráficos para que este servidor MCP consulte, por lo que la mayoría de los usuarios deberían comenzar con los servidores de API y Búsqueda.

Características:

Servidor de API PDBe: Acceda a datos estructurales principales a través de endpoints de API REST
Servidor de Búsqueda PDBe: Realice búsquedas avanzadas basadas en Solr en datos estructurales
Servidor de Gráfico PDBe: Inspeccione el esquema del gráfico y, con una configuración local de PDBe-KB Neo4j, consulte relaciones complejas e interacciones moleculares

Requisitos previos

Python 3.10+ - Requerido para el tiempo de ejecución del servidor
uv - Gestor de paquetes Python rápido y resolvedor de dependencias

Instalación

Inicio rápido

Ejecutar directamente desde PyPI:

uvx pdbe-mcp-server

La herramienta está disponible en PyPI y se puede ejecutar directamente con uvx sin ningún paso de instalación.

Alternativa: Instalación local para desarrollo

Para trabajo de desarrollo o personalización:

Clonar y navegar al repositorio:

git clone https://github.com/PDBeurope/PDBe-MCP-Servers.git
cd PDBe-MCP-Servers

Crear un entorno virtual:
```
uv venv
```
Instalar con uv:
```
uv pip install .
```

Integración con clientes de IA

Configuración

Abra la configuración MCP de su cliente de IA.

Los clientes compatibles con MCP utilizan diferentes ubicaciones de configuración y formatos de archivo. Muchos clientes basados en JSON utilizan un objeto mcpServers, mientras que algunos clientes proporcionan comandos o una interfaz de configuración para agregar servidores.

Agregue la configuración recomendada del servidor MCP de PDBe.

Para clientes basados en JSON que admiten mcpServers, agregue:

Para instalación desde PyPI (recomendado):

{
  "mcpServers": {
    "PDBe API Server": {
      "command": "uvx",
      "args": [
        "pdbe-mcp-server",
        "--server-type",
        "pdbe_api_server"
      ]
    },
    "PDBe Search Server": {
      "command": "uvx",
      "args": [
        "pdbe-mcp-server",
        "--server-type",
        "pdbe_search_server"
      ]
    }
  }
}

Para instalación local de desarrollo:

{
  "mcpServers": {
    "PDBe API": {
      "command": "/usr/local/bin/uv",
      "args": [
        "run",
        "--directory",
        "/path/to/your/PDBe-MCP-Servers",
        "pdbe-mcp-server",
        "--server-type",
        "pdbe_api_server"
      ]
    },
    "PDBe Search": {
      "command": "/usr/local/bin/uv",
      "args": [
        "run",
        "--directory",
        "/path/to/your/PDBe-MCP-Servers",
        "pdbe-mcp-server",
        "--server-type",
        "pdbe_search_server"
      ]
    }
  }
}

Nota:

Para el método de instalación desde PyPI, asegúrese de que uvx esté disponible en su PATH (esto viene con uv)

Para desarrollo local, asegúrese de que uv esté instalado y que /path/to/your/PDBe-MCP-Servers coincida con su directorio real

Agregue el servidor de gráficos solo si tiene una base de datos de gráficos local PDBe-KB Neo4j configurada. Consulte Configuración avanzada del servidor de gráficos.

Reinicie o recargue su cliente de IA para cargar la nueva configuración.

Ejemplo en Antigravity

En Antigravity, abra Gestionar servidores MCP y seleccione Ver configuración sin procesar, o edite ~/.gemini/antigravity/mcp_config.json, luego agregue las entradas del servidor PDBe:

{
  "mcpServers": {
    "PDBe API Server": {
      "command": "uvx",
      "args": [
        "pdbe-mcp-server",
        "--server-type",
        "pdbe_api_server"
      ]
    },
    "PDBe Search Server": {
      "command": "uvx",
      "args": [
        "pdbe-mcp-server",
        "--server-type",
        "pdbe_search_server"
      ]
    }
  }
}

Ejemplo en Codex

En Codex, agregue los servidores MCP de PDBe con la CLI:

codex mcp add pdbe-api -- uvx pdbe-mcp-server --server-type pdbe_api_server
codex mcp add pdbe-search -- uvx pdbe-mcp-server --server-type pdbe_search_server
codex mcp list

Para una copia local de desarrollo, apunte Codex al directorio del repositorio:

codex mcp add pdbe-api-local -- uv run --directory /path/to/your/PDBe-MCP-Servers pdbe-mcp-server --server-type pdbe_api_server
codex mcp add pdbe-search-local -- uv run --directory /path/to/your/PDBe-MCP-Servers pdbe-mcp-server --server-type pdbe_search_server

Uso en un cliente de IA

Una vez configurado, puede acceder a las herramientas de PDBe directamente en las conversaciones de su cliente de IA:

Buscar estructuras de proteínas: "Encuentra estructuras para el acceso UniProt P12345"
Consultar lanzamientos de estructuras: "Muéstrame todas las estructuras lanzadas este mes agrupadas por método experimental"
Consultas de búsqueda avanzada: "Encuentra todas las estructuras cristalinas de rayos X con resolución mejor que 2.0 Å de 2024"

Las herramientas aparecerán en la interfaz de herramientas de su cliente de IA, donde podrá habilitarlas o deshabilitarlas según sea necesario.

Tipos de servidores

pdbe_api_server: Acceso principal a la API REST de PDBe con datos estructurales esenciales
pdbe_search_server: Capacidades de búsqueda avanzada basadas en Solr para consultas estructurales complejas y análisis de datos
pdbe_graph_server: Servidor avanzado/local para inspeccionar el esquema del gráfico PDBe-KB y opcionalmente ejecutar consultas Cypher de solo lectura contra una base de datos Neo4j configurada localmente

Referencia de herramientas

Herramientas del servidor de API

El pdbe_api_server genera herramientas a partir de la especificación OpenAPI de la API PDBe. Use este servidor para datos principales de la API REST de PDBe, como entradas, ensamblajes, moléculas, ligandos, publicaciones e información de validación.

Herramientas del servidor de búsqueda

`get_pdbe_search_schema`

Recupera el esquema completo de búsqueda Solr mostrando todos los campos disponibles, tipos de datos y descripciones. Úselo para comprender qué campos puede buscar y filtrar.

Ejemplo de uso:

"Show me the search schema for PDBe structures"

`run_pdbe_search_query`

Ejecute consultas de búsqueda estilo Solr con selección flexible de campos, consultas de filtro, facetas, agrupación, ordenamiento y opciones de paginación.

Parámetros:

query (obligatorio): Cadena de consulta Solr sin procesar pasada como q (p. ej., *:*, pdb_id:1cbs, text:*kinase*, resolution:[0 TO 2.0])
fl (opcional): Lista de campos como cadena o matriz de nombres de campos para incluir en los resultados
filters (opcional): Alias compatible con versiones anteriores para fl
fq (opcional): Cadena de consulta de filtro o matriz de cadenas de consulta de filtro
sort (opcional): Criterios de ordenamiento (p. ej., release_date desc, resolution asc)
start (opcional): Índice inicial para paginación (predeterminado: 0)
rows (opcional): Número de resultados a devolver (predeterminado: 10)
facet (opcional): Habilitar facetas Solr
facet_fields (opcional): Cadena o matriz de facetas de campo, enviada como facet.field
facet_queries (opcional): Cadena o matriz de facetas de consulta, enviada como facet.query
facet_limit, facet_mincount, facet_sort (opcional): Controles comunes de facetas
group (opcional): Habilitar agrupación Solr
group_field (opcional): Cadena o matriz de campos de agrupación, enviada como group.field
group_limit, group_offset, group_sort (opcional): Controles comunes de agrupación
params (opcional): Objeto de parámetros Solr adicionales para uso avanzado

Consultas de ejemplo:

{
  "query": "*:*",
  "fq": ["release_date:[2025-10-01T00:00:00Z TO 2025-10-31T23:59:59Z]"],
  "group": true,
  "group_field": "experimental_method",
  "rows": 0
}

{
  "query": "*:*",
  "fq": ["experimental_method:\"X-ray diffraction\"", "resolution:[0 TO 2.0]"],
  "fl": ["pdb_id", "title", "resolution", "experimental_method"],
  "sort": "resolution asc",
  "rows": 20
}

{
  "query": "text:*ATP*",
  "facet": true,
  "facet_fields": ["ligand_name", "experimental_method"],
  "facet_mincount": 1,
  "rows": 10
}

Ejemplos de campos de búsqueda

Los campos de búsqueda comunes incluyen:

pdb_id: Identificador de entrada PDB
experimental_method: Método de determinación de estructura
release_date: Fecha de lanzamiento de la estructura
resolution: Resolución de la estructura (Å)
molecule_type: Tipo de molécula (proteína, ADN, ARN, etc.)
organism_scientific_name: Organismo de origen
ligand_name: Ligandos unidos
title: Título/descripción de la estructura

Use get_pdbe_search_schema para descubrir todos los campos disponibles y sus descripciones.

Desarrollo y uso avanzado

Instalación para desarrollo

Para contribuciones o trabajo de desarrollo, primero clone el repositorio y luego instale en modo editable:

git clone https://github.com/PDBeurope/PDBe-MCP-Servers.git
cd PDBe-MCP-Servers
uv sync --all-extras --dev

Node.js (opcional) - Para usar la herramienta de desarrollo MCP Inspector

Iniciar el servidor manualmente

La mayoría de los usuarios deberían ejecutar el servidor de API, el servidor de Búsqueda, o ambos.

Servidor de API PDBe

Proporciona acceso a los endpoints principales de la API REST de PDBe:

Usando instalación desde PyPI:

uvx pdbe-mcp-server --server-type pdbe_api_server --transport sse

Usando desarrollo local:

uv run pdbe-mcp-server --server-type pdbe_api_server --transport sse

Servidor de Búsqueda PDBe

Proporciona capacidades avanzadas de búsqueda y análisis basadas en Solr:

Usando instalación desde PyPI:

uvx pdbe-mcp-server --server-type pdbe_search_server --transport sse

Usando desarrollo local:

uv run pdbe-mcp-server --server-type pdbe_search_server --transport sse

El servidor se iniciará en http://localhost:8000/sse de forma predeterminada.

Configuración avanzada del servidor de gráficos

El pdbe_graph_server está destinado a usuarios que han descargado y configurado la base de datos de gráficos PDBe-KB en su propio entorno. PDBe no proporciona una instancia pública de Neo4j para que este servidor MCP consulte.

Para configurar la base de datos de gráficos localmente, siga la documentación del gráfico PDBe-KB: https://www.ebi.ac.uk/pdbe/pdbe-kb/graph

Una vez que su base de datos local Neo4j esté en ejecución, configure estas variables de entorno antes de iniciar el servidor de gráficos:

NEO4J_URL: La URL de la base de datos Neo4j (p. ej., bolt://localhost:7687)
NEO4J_USERNAME: El nombre de usuario de Neo4j
NEO4J_PASSWORD: La contraseña de Neo4j
NEO4J_DATABASE (opcional): El nombre de la base de datos. Cuando se configura, se pasa al controlador Neo4j para Neo4j 4+. Para compatibilidad con Neo4j 3.5, omita esta variable para usar la base de datos predeterminada.

El controlador Neo4j está incluido en las dependencias de este paquete.

Configuración del gráfico en clientes MCP

Agregue este servidor solo cuando las variables de entorno anteriores estén disponibles para su cliente de IA.

Para instalación desde PyPI:

{
  "mcpServers": {
    "PDBe Graph Server": {
      "command": "uvx",
      "args": [
        "pdbe-mcp-server",
        "--server-type",
        "pdbe_graph_server"
      ],
      "env": {
        "NEO4J_URL": "bolt://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "your-password"
      }
    }
  }
}

Para instalación local de desarrollo:

{
  "mcpServers": {
    "PDBe Graph": {
      "command": "/usr/local/bin/uv",
      "args": [
        "run",
        "--directory",
        "/path/to/your/PDBe-MCP-Servers",
        "pdbe-mcp-server",
        "--server-type",
        "pdbe_graph_server"
      ],
      "env": {
        "NEO4J_URL": "bolt://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "your-password"
      }
    }
  }
}

Ejemplo en Codex:

codex mcp add pdbe-graph \
  --env NEO4J_URL=bolt://localhost:7687 \
  --env NEO4J_USERNAME=neo4j \
  --env NEO4J_PASSWORD=your-password \
  -- uvx pdbe-mcp-server --server-type pdbe_graph_server

Iniciar el servidor de gráficos manualmente

Usando instalación desde PyPI:

uvx pdbe-mcp-server --server-type pdbe_graph_server --transport sse

Usando desarrollo local:

uv run pdbe-mcp-server --server-type pdbe_graph_server --transport sse

Herramientas del servidor de gráficos

`pdbe_graph_nodes`

Recupera metadatos sobre todos los tipos de nodos (etiquetas) definidos en el esquema de la base de datos de gráficos PDBe. Esto utiliza el esquema de gráficos público y no requiere credenciales locales de Neo4j.

Ejemplo de uso:

"Show me all node types in the PDBe graph database"

`pdbe_graph_edges`

Recupera metadatos sobre todos los tipos de relaciones (bordes) definidos en el esquema de la base de datos de gráficos PDBe. Esto utiliza el esquema de gráficos público y no requiere credenciales locales de Neo4j.

Ejemplo de uso:

"Show me all relationship types in the PDBe graph database"

`pdbe_graph_node_relationships`

Verifica etiquetas de nodos seleccionadas y devuelve los patrones de relación entrantes, salientes y de auto-bucle definidos para cada etiqueta. Esto utiliza el esquema de gráficos público y no requiere credenciales locales de Neo4j.

Parámetros:

node_labels (obligatorio): Lista de etiquetas de nodos exactas, sensibles a mayúsculas y minúsculas, para verificar.

Ejemplo de uso:

"Verify relationships for Entry, Entity, and UniProt"

`pdbe_graph_example_queries`

Recupera consultas Cypher de ejemplo que demuestran cómo interactuar con la base de datos de gráficos PDBe. Esto utiliza el esquema de gráficos público y no requiere credenciales locales de Neo4j.

Ejemplo de uso:

"Give me example Cypher queries for exploring the PDBe graph"

`pdbe_run_cypher_query`

Ejecute consultas Cypher personalizadas de solo lectura contra su base de datos de gráficos Neo4j configurada. Esta herramienta solo está disponible cuando las variables de entorno de Neo4j están configuradas.

Parámetros:

cypher_query (obligatorio): La consulta Cypher a ejecutar. Solo se permiten consultas MATCH y OPTIONAL MATCH.

Ejemplo de uso:

"Execute query: MATCH (s:Structure) WHERE s.PDB_ID = '1abc' RETURN s.TITLE as title"
"Find ligands: MATCH (s:Structure)-[:HAS_LIGAND]->(l:Ligand) WHERE s.PDB_ID = '1abc' RETURN l.name"

Seguridad: Solo se permiten consultas de solo lectura (MATCH, OPTIONAL MATCH). Las operaciones de escritura (MERGE, CREATE, DELETE, REMOVE, SET, LOAD CSV, FOREACH) están bloqueadas para evitar la modificación accidental de datos.

La respuesta de la herramienta se formatea como JSON de forma predeterminada, pero se puede convertir al formato TOON configurando TOON_ENABLED=true.

Desarrollo y pruebas

Explore las herramientas disponibles y pruebe las respuestas de la API:

npx @modelcontextprotocol/inspector

El MCP Inspector proporciona una interfaz interactiva para explorar herramientas, probar consultas y validar respuestas antes de integrarlas con su aplicación.

Configuración del servidor

Opciones de transporte

stdio: Modo predeterminado - Óptimo para integración directa con clientes MCP
SSE (Eventos enviados por el servidor): --transport sse - Mejor para clientes basados en web y desarrollo

Salida TOON experimental

Puede habilitar la salida experimental en formato TOON para las respuestas de las herramientas de la API PDBe y los resultados de consultas Cypher de Neo4j configurando la variable de entorno TOON_ENABLED=true. Consulte la especificación del formato TOON en https://toonformat.dev/.

Si la codificación TOON falla por cualquier motivo, el servidor vuelve a la salida JSON.
Esta característica es experimental y está destinada solo para uso opcional.

Solución de problemas

Problemas comunes

Errores de "Comando no encontrado":

Asegúrese de que uv esté instalado y en su PATH
Verifique la ruta completa a uv en la configuración MCP de su cliente de IA

Herramientas faltantes en su cliente de IA:

Reinicie o recargue su cliente de IA después de los cambios de configuración
Revise los registros del servidor MCP de su cliente de IA para ver si hay errores
Verifique la sintaxis JSON en su archivo de configuración

Recursos

Protocolo de Contexto de Modelo - Documentación y especificaciones oficiales de MCP
Documentación de la API PDBe - Referencia completa de la API y ejemplos
Base de datos de gráficos PDBe - Consultas avanzadas y mapeo de relaciones
Documentación MCP de Antigravity - Instrucciones de configuración MCP para Antigravity
Docs MCP de OpenAI - Ejemplos de configuración MCP de Codex

Licencia

Este proyecto está licenciado bajo la Licencia Apache, Versión 2.0 - consulte el archivo LICENCIA para más detalles.

Soporte

Para preguntas, informes de errores o solicitudes de funciones:

Problemas: Utilice el rastreador de GitHub Issues
Mesa de ayuda de PDBe: Visite las páginas de Ayuda y Soporte de PDBe