PDBe MCP Servers

A set of Model Context Protocol (MCP) servers that provides seamless access to the Protein Data Bank in Europe (PDBe) API and PDBe Search. These servers expose PDBe's comprehensive structural biology data as MCP tools, enabling direct integration with any AI client that supports MCP.

The package also includes an advanced PDBe Graph server for users who run their own local PDBe-KB Neo4j graph database. PDBe does not provide a public running graph database instance for this MCP server to query, so most users should start with the API and Search servers.

- PDBe API Server: Access core structural data through REST API endpoints
- PDBe Search Server: Perform advanced Solr-based searches across structural data
- PDBe Graph Server: Inspect the graph schema and, with a local PDBe-KB Neo4j setup, query complex relationships and molecular interactions

- Python 3.10+- Required for the server runtime
- uv- Fast Python package manager and dependency resolver

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

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

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

- For the PyPI installation method, ensureuvxis available in your PATH (this comes with uv)
- For local development, ensure thatuvis installed and the/path/to/your/PDBe-MCP-Serversmatches your actual directory

Add the graph server only if you have a local PDBe-KB Neo4j graph database configured. SeeAdvanced Graph Server Configuration.
- Restart or reload your AI clientto load the new configuration.

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

In Codex, add the PDBe MCP servers with the 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

For a local development checkout, point Codex at the repository directory:

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

Once configured, you can access PDBe tools directly in your AI client conversations:

- Search for protein structures: "Find structures for UniProt accession P12345"
- Query structure releases: "Show me all structures released this month grouped by experimental method"
- Advanced search queries: "Find all X-ray crystal structures with resolution better than 2.0 Å from 2024"

The tools will appear in your AI client's tools interface, where you can enable or disable them as needed.

- pdbe_api_server: Core PDBe REST API access with essential structural data
- pdbe_search_server: Advanced Solr-based search capabilities for complex structural queries and data analysis
- pdbe_graph_server: Advanced/local server for inspecting the PDBe-KB graph schema and optionally executing read-only Cypher queries against a locally configured Neo4j database

Thepdbe_api_servergenerates tools from the PDBe API OpenAPI specification. Use this server for core PDBe REST API data, such as entries, assemblies, molecules, ligands, publications, and validation information.

Retrieves the complete Solr search schema showing all available fields, data types, and descriptions. Use this to understand what fields you can search and filter on.

"Show me the search schema for PDBe structures"

Execute Solr-style search queries with flexible field selection, filter queries, facets, grouping, sorting, and pagination options.

- query(required): Raw Solr query string passed asq(e.g.,:,pdb_id:1cbs,text:kinase,resolution:[0 TO 2.0])
- fl(optional): Field list as a string or array of field names to include in results
- filters(optional): Backwards-compatible alias forfl
- fq(optional): Filter query string or array of filter query strings
- sort(optional): Sort criteria (e.g.,release_date desc,resolution asc)
- start(optional): Starting index for pagination (default: 0)
- rows(optional): Number of results to return (default: 10)
- facet(optional): Enable Solr faceting
- facet_fields(optional): Field facet string or array, sent asfacet.field
- facet_queries(optional): Query facet string or array, sent asfacet.query
- facet_limit,facet_mincount,facet_sort(optional): Common facet controls
- group(optional): Enable Solr grouping
- group_field(optional): Grouping field string or array, sent asgroup.field
- group_limit,group_offset,group_sort(optional): Common grouping controls
- params(optional): Object of additional Solr parameters for advanced use

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

- pdb_id: PDB entry identifier
- experimental_method: Structure determination method
- release_date: Structure release date
- resolution: Structure resolution (Å)
- molecule_type: Type of molecule (protein, DNA, RNA, etc.)
- organism_scientific_name: Source organism
- ligand_name: Bound ligands
- title: Structure title/description

Useget_pdbe_search_schemato discover all available fields and their descriptions.

For contributing or development work, first clone the repository and then install in editable mode:

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

Node.js(optional) - For using the MCP Inspector development tool

Most users should run the API server, the Search server, or both.

Provides access to core PDBe REST API endpoints:

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

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

Provides advanced Solr-based search and analytics capabilities:

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

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

The server will start athttp://localhost:8000/sseby default.

Thepdbe_graph_serveris intended for users who have downloaded and configured the PDBe-KB graph database in their own environment. PDBe does not provide a public running Neo4j instance for this MCP server to query.

To set up the graph database locally, follow the PDBe-KB graph documentation:https://www.ebi.ac.uk/pdbe/pdbe-kb/graph

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

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

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

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

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

Retrieves metadata about all node types (labels) defined in the PDBe graph database schema. This uses the public graph schema and does not require local Neo4j credentials.

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

Retrieves metadata about all relationship types (edges) defined in the PDBe graph database schema. This uses the public graph schema and does not require local Neo4j credentials.

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

Verifies selected node labels and returns the incoming, outgoing, and self-loop relationship patterns defined for each label. This uses the public graph schema and does not require local Neo4j credentials.

- node_labels(required): List of exact, case-sensitive node labels to verify.

"Verify relationships for Entry, Entity, and UniProt"

Retrieves example Cypher queries that demonstrate how to interact with the PDBe graph database. This uses the public graph schema and does not require local Neo4j credentials.

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

Execute custom read-only Cypher queries against your configured Neo4j graph database. This tool is only available when Neo4j environment variables are configured.

- cypher_query(required): The Cypher query to execute. Only MATCH and OPTIONAL MATCH queries are allowed.

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

Security:Only read-only queries are allowed (MATCH, OPTIONAL MATCH). Write operations (MERGE, CREATE, DELETE, REMOVE, SET, LOAD CSV, FOREACH) are blocked to prevent accidental data modification.

The tool response is formatted as JSON by default, but can be converted to TOON format by settingTOON_ENABLED=true.

Explore available tools and test API responses:

The MCP Inspector provides an interactive interface to browse tools, test queries, and validate responses before integrating with your application.

- stdio: Default mode - Optimal for direct MCP client integration
- SSE (Server-Sent Events):--transport sse- Best for web-based clients and development

You can enable experimental TOON-formatted output for PDBe API tool responses and Neo4j Cypher query results by setting the environment variableTOON_ENABLED=true. See the TOON format specification athttps://toonformat.dev/.

- Model Context Protocol- Official MCP documentation and specifications
- PDBe API Documentation- Complete API reference and examples
- PDBe Graph Database- Advanced querying and relationship mapping
- Antigravity MCP Documentation- MCP setup instructions for Antigravity
- OpenAI Docs MCP- Codex MCP configuration examples

This project is licensed under the Apache License, Version 2.0 - see theLICENSEfile for details.