PDBe MCP Servers

Servidores MCP do PDBe (Oficiais) da equipe PDBe integram os recursos do Protein Data Bank Europe com LLMs por meio do Model Context Protocol. Oferece acesso contínuo a dados de estrutura de proteínas por meio de ferramentas de API e assistência de esquema de banco de dados gráfico para geração inteligente de consultas Cypher, conectando biologia estrutural e pesquisa em IA.

GitHub

Experimente este MCPPatrocinado

Documentação

Servidores MCP PDBe

Um conjunto de servidores Model Context Protocol (MCP) que fornece acesso contínuo à API do Protein Data Bank in Europe (PDBe) e à busca PDBe. Esses servidores expõem os dados abrangentes de biologia estrutural do PDBe como ferramentas MCP, permitindo integração direta com qualquer cliente de IA que suporte MCP.

O pacote também inclui um servidor avançado PDBe Graph para usuários que executam seu próprio banco de dados gráfico local PDBe-KB Neo4j. O PDBe não fornece uma instância pública de banco de dados gráfico para este servidor MCP consultar, então a maioria dos usuários deve começar com os servidores API e Search.

Recursos:

Servidor PDBe API: Acesse dados estruturais principais por meio de endpoints REST API
Servidor PDBe Search: Realize buscas avançadas baseadas em Solr em dados estruturais
Servidor PDBe Graph: Inspecione o esquema do grafo e, com uma configuração local PDBe-KB Neo4j, consulte relacionamentos complexos e interações moleculares

Pré-requisitos

Python 3.10+ - Necessário para o runtime do servidor
uv - Gerenciador de pacotes Python rápido e resolvedor de dependências

Instalação

Início Rápido

Execute diretamente do PyPI:

uvx pdbe-mcp-server

A ferramenta está disponível no PyPI e pode ser executada diretamente com uvx sem qualquer etapa de instalação.

Alternativa: Instalação Local para Desenvolvimento

Para trabalho de desenvolvimento ou personalização:

Clone e navegue até o repositório:

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

Crie um ambiente virtual:
```
uv venv
```
Instale com uv:
```
uv pip install .
```

Integração com Cliente de IA

Configuração

Abra a configuração MCP do seu cliente de IA.

Clientes compatíveis com MCP usam diferentes locais de configuração e formatos de arquivo. Muitos clientes baseados em JSON usam um objeto mcpServers, enquanto alguns clientes fornecem comandos ou uma interface de configurações para adicionar servidores.

Adicione a configuração recomendada do servidor MCP PDBe.

Para clientes baseados em JSON que suportam mcpServers, adicione:

Para instalação via 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 instalação local de desenvolvimento:

{
  "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 o método de instalação via PyPI, certifique-se de que uvx esteja disponível no seu PATH (isso vem com uv)

Para desenvolvimento local, certifique-se de que uv esteja instalado e que /path/to/your/PDBe-MCP-Servers corresponda ao seu diretório real

Adicione o servidor graph apenas se você tiver um banco de dados gráfico local PDBe-KB Neo4j configurado. Veja Configuração Avançada do Servidor Graph.

Reinicie ou recarregue seu cliente de IA para carregar a nova configuração.

Exemplo no Antigravity

No Antigravity, abra Gerenciar Servidores MCP e selecione Ver configuração bruta, ou edite ~/.gemini/antigravity/mcp_config.json, depois adicione as entradas do 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"
      ]
    }
  }
}

Exemplo no Codex

No Codex, adicione os servidores MCP PDBe com a 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 um checkout de desenvolvimento local, aponte o Codex para o diretório do repositório:

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 em um Cliente de IA

Uma vez configurado, você pode acessar as ferramentas PDBe diretamente nas conversas do seu cliente de IA:

Buscar estruturas de proteínas: "Encontre estruturas para o acesso UniProt P12345"
Consultar lançamentos de estruturas: "Mostre-me todas as estruturas lançadas este mês agrupadas por método experimental"
Consultas de busca avançadas: "Encontre todas as estruturas cristalográficas de raios X com resolução melhor que 2,0 Å de 2024"

As ferramentas aparecerão na interface de ferramentas do seu cliente de IA, onde você pode ativá-las ou desativá-las conforme necessário.

Tipos de Servidor

pdbe_api_server: Acesso principal à API REST PDBe com dados estruturais essenciais
pdbe_search_server: Capacidades avançadas de busca baseadas em Solr para consultas estruturais complexas e análise de dados
pdbe_graph_server: Servidor avançado/local para inspecionar o esquema do grafo PDBe-KB e opcionalmente executar consultas Cypher somente leitura contra um banco de dados Neo4j configurado localmente

Referência de Ferramentas

Ferramentas do Servidor API

O pdbe_api_server gera ferramentas a partir da especificação OpenAPI da API PDBe. Use este servidor para dados principais da API REST PDBe, como entradas, montagens, moléculas, ligantes, publicações e informações de validação.

Ferramentas do Servidor Search

`get_pdbe_search_schema`

Recupera o esquema completo de busca Solr mostrando todos os campos disponíveis, tipos de dados e descrições. Use isso para entender quais campos você pode buscar e filtrar.

Exemplo de uso:

"Show me the search schema for PDBe structures"

`run_pdbe_search_query`

Execute consultas de busca no estilo Solr com seleção flexível de campos, consultas de filtro, facetas, agrupamento, ordenação e opções de paginação.

Parâmetros:

query (obrigatório): String de consulta Solr bruta passada como q (ex.: *:*, pdb_id:1cbs, text:*kinase*, resolution:[0 TO 2.0])
fl (opcional): Lista de campos como string ou array de nomes de campos a incluir nos resultados
filters (opcional): Alias compatível com versões anteriores para fl
fq (opcional): String de consulta de filtro ou array de strings de consulta de filtro
sort (opcional): Critérios de ordenação (ex.: release_date desc, resolution asc)
start (opcional): Índice inicial para paginação (padrão: 0)
rows (opcional): Número de resultados a retornar (padrão: 10)
facet (opcional): Ativar facetas Solr
facet_fields (opcional): String de faceta de campo ou array, enviado como facet.field
facet_queries (opcional): String de faceta de consulta ou array, enviado como facet.query
facet_limit, facet_mincount, facet_sort (opcional): Controles comuns de facetas
group (opcional): Ativar agrupamento Solr
group_field (opcional): String de campo de agrupamento ou array, enviado como group.field
group_limit, group_offset, group_sort (opcional): Controles comuns de agrupamento
params (opcional): Objeto de parâmetros Solr adicionais para uso avançado

Exemplos de consultas:

{
  "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
}

Exemplos de Campos de Busca

Campos comuns pesquisáveis incluem:

pdb_id: Identificador da entrada PDB
experimental_method: Método de determinação da estrutura
release_date: Data de lançamento da estrutura
resolution: Resolução da estrutura (Å)
molecule_type: Tipo de molécula (proteína, DNA, RNA, etc.)
organism_scientific_name: Organismo de origem
ligand_name: Ligantes ligados
title: Título/descrição da estrutura

Use get_pdbe_search_schema para descobrir todos os campos disponíveis e suas descrições.

Desenvolvimento e Uso Avançado

Instalação para Desenvolvimento

Para contribuições ou trabalho de desenvolvimento, primeiro clone o repositório e depois instale em modo editável:

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

Node.js (opcional) - Para usar a ferramenta de desenvolvimento MCP Inspector

Iniciando o Servidor Manualmente

A maioria dos usuários deve executar o servidor API, o servidor Search, ou ambos.

Servidor PDBe API

Fornece acesso aos endpoints principais da API REST PDBe:

Usando instalação via PyPI:

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

Usando desenvolvimento local:

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

Servidor PDBe Search

Fornece capacidades avançadas de busca e análise baseadas em Solr:

Usando instalação via PyPI:

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

Usando desenvolvimento local:

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

O servidor iniciará em http://localhost:8000/sse por padrão.

Configuração Avançada do Servidor Graph

O pdbe_graph_server é destinado a usuários que baixaram e configuraram o banco de dados gráfico PDBe-KB em seu próprio ambiente. O PDBe não fornece uma instância Neo4j pública em execução para este servidor MCP consultar.

Para configurar o banco de dados gráfico localmente, siga a documentação do grafo PDBe-KB: https://www.ebi.ac.uk/pdbe/pdbe-kb/graph

Quando seu banco de dados Neo4j local estiver em execução, defina estas variáveis de ambiente antes de iniciar o servidor graph:

NEO4J_URL: A URL do banco de dados Neo4j (ex.: bolt://localhost:7687)
NEO4J_USERNAME: O nome de usuário do Neo4j
NEO4J_PASSWORD: A senha do Neo4j
NEO4J_DATABASE (opcional): O nome do banco de dados. Quando definido, é passado ao driver Neo4j para Neo4j 4+. Para compatibilidade com Neo4j 3.5, omita esta variável para usar o banco de dados padrão.

O driver Neo4j está incluído nas dependências deste pacote.

Configuração do Graph no Cliente MCP

Adicione este servidor apenas quando as variáveis de ambiente acima estiverem disponíveis para seu cliente de IA.

Para instalação via 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 instalação local de desenvolvimento:

{
  "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"
      }
    }
  }
}

Exemplo no 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

Iniciando o Servidor Graph Manualmente

Usando instalação via PyPI:

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

Usando desenvolvimento local:

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

Ferramentas do Servidor Graph

`pdbe_graph_nodes`

Recupera metadados sobre todos os tipos de nós (rótulos) definidos no esquema do banco de dados gráfico PDBe. Isso usa o esquema público do grafo e não requer credenciais Neo4j locais.

Exemplo de uso:

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

`pdbe_graph_edges`

Recupera metadados sobre todos os tipos de relacionamentos (arestas) definidos no esquema do banco de dados gráfico PDBe. Isso usa o esquema público do grafo e não requer credenciais Neo4j locais.

Exemplo de uso:

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

`pdbe_graph_node_relationships`

Verifica rótulos de nós selecionados e retorna os padrões de relacionamento de entrada, saída e auto-loop definidos para cada rótulo. Isso usa o esquema público do grafo e não requer credenciais Neo4j locais.

Parâmetros:

node_labels (obrigatório): Lista de rótulos de nós exatos, sensíveis a maiúsculas/minúsculas, a verificar.

Exemplo de uso:

"Verify relationships for Entry, Entity, and UniProt"

`pdbe_graph_example_queries`

Recupera exemplos de consultas Cypher que demonstram como interagir com o banco de dados gráfico PDBe. Isso usa o esquema público do grafo e não requer credenciais Neo4j locais.

Exemplo de uso:

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

`pdbe_run_cypher_query`

Execute consultas Cypher personalizadas somente leitura contra seu banco de dados gráfico Neo4j configurado. Esta ferramenta está disponível apenas quando as variáveis de ambiente Neo4j estão configuradas.

Parâmetros:

cypher_query (obrigatório): A consulta Cypher a executar. Apenas consultas MATCH e OPTIONAL MATCH são permitidas.

Exemplo 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"

Segurança: Apenas consultas somente leitura são permitidas (MATCH, OPTIONAL MATCH). Operações de escrita (MERGE, CREATE, DELETE, REMOVE, SET, LOAD CSV, FOREACH) são bloqueadas para evitar modificação acidental de dados.

A resposta da ferramenta é formatada como JSON por padrão, mas pode ser convertida para o formato TOON definindo TOON_ENABLED=true.

Desenvolvimento e Testes

Explore as ferramentas disponíveis e teste respostas da API:

npx @modelcontextprotocol/inspector

O MCP Inspector fornece uma interface interativa para navegar pelas ferramentas, testar consultas e validar respostas antes de integrar com sua aplicação.

Configuração do Servidor

Opções de Transporte

stdio: Modo padrão - Ideal para integração direta com cliente MCP
SSE (Server-Sent Events): --transport sse - Melhor para clientes baseados na web e desenvolvimento

Saída Experimental TOON

Você pode habilitar a saída experimental no formato TOON para respostas de ferramentas da API PDBe e resultados de consultas Cypher Neo4j definindo a variável de ambiente TOON_ENABLED=true. Veja a especificação do formato TOON em https://toonformat.dev/.

Se a codificação TOON falhar por qualquer motivo, o servidor volta para saída JSON.
Este recurso é experimental e destinado apenas para uso opt-in.

Solução de Problemas

Problemas Comuns

Erros de "Comando não encontrado":

Certifique-se de que uv esteja instalado e no seu PATH
Verifique o caminho completo para uv na configuração MCP do seu cliente de IA

Ferramentas ausentes no seu cliente de IA:

Reinicie ou recarregue seu cliente de IA após alterações de configuração
Verifique os logs do servidor MCP do seu cliente de IA para erros
Verifique a sintaxe JSON no seu arquivo de configuração

Recursos

Model Context Protocol - Documentação e especificações oficiais do MCP
Documentação da API PDBe - Referência completa da API e exemplos
Banco de Dados Gráfico PDBe - Consultas avançadas e mapeamento de relacionamentos
Documentação MCP do Antigravity - Instruções de configuração MCP para Antigravity
Docs MCP da OpenAI - Exemplos de configuração MCP do Codex

Licença

Este projeto é licenciado sob a Apache License, Versão 2.0 - veja o arquivo LICENSE para detalhes.

Suporte

Para perguntas, relatórios de bugs ou solicitações de recursos:

Issues: Use o rastreador de GitHub Issues
PDBe Helpdesk: Visite as páginas de PDBe Help & Support