Metadata-Version: 2.4
Name: pdbe-mcp-server
Version: 2.0.0
Summary: A Model Context Protocol (MCP) server for accessing PDBe (Protein Data Bank in Europe) structural biology data and services
Author-email: Sreenath Sasidharan Nair <sreenath@ebi.ac.uk>
License: Apache-2.0
License-File: LICENSE
Keywords: automation,fetch,http,llm,mcp,stateless,streamable,web
Requires-Python: >=3.11
Requires-Dist: anyio<5,>=4.5
Requires-Dist: click<9,>=8.1
Requires-Dist: httpx<1,>=0.27
Requires-Dist: mcp<2,>=1.27
Requires-Dist: molviewspec<2,>=1.8.1
Requires-Dist: neo4j<6,>=5
Requires-Dist: omegaconf<3,>=2.3
Requires-Dist: pyyaml<7,>=6
Requires-Dist: requests<3,>=2.33
Requires-Dist: starlette<2,>=1.0.1
Requires-Dist: toon-format<2,>=1
Requires-Dist: typing-extensions<5,>=4.1
Requires-Dist: uvicorn<1,>=0.30
Description-Content-Type: text/markdown

# PDBe MCP Servers

Access Protein Data Bank in Europe (PDBe) structural biology data from any
AI client that supports the Model Context Protocol (MCP).

## Capabilities

### Molecular workspace (MCP Apps)

In an MCP Apps client, the Apps server provides a shared Mol* workspace for:

- **Structure Explorer:** inspect chains, residues, ligand instances, and
  source annotations, with linked sequence and annotation tracks.
- **Ligand & Binding Site Explorer:** inspect PDBe-reported ligand interaction
  records, filter evidence, and export contacts.
- **Structure Comparison:** view PDBe's precomputed superpositions and
  PDBe/SIFTS residue correspondence, with a correspondence table and CSV export.
- **MolViewSpec Builder and Stories:** create custom scenes and ordered
  multi-scene molecular stories.
- **Workspace management:** save or restore workspace JSON, export MVSJ, and
  update scenes and layers through MCP tools.

Use `pdbe_apps_server` for the dedicated server or the recommended `all`
server; connection examples are below. The host needs MCP Apps support, WebGL,
and access to `https://www.ebi.ac.uk`.
Clients without UI support receive text and structured data fallbacks.

Comparisons use supplied PDBe transforms and mappings; the app does not
calculate a new fit, RMSD, or proximity-derived binding sites. The ligand
explorer displays PDBe-supplied interaction records rather than calculating new
contacts. Chain selectors use label chain IDs (`struct_asym_id`).

Example prompts for an MCP Apps-capable client:

- “Open PDB entry 1tqn in the molecular workspace.”
- “Compare the alpha chains of human deoxy- and oxyhemoglobin (PDB 4hhb and
  1hho) and show their residue correspondence.”
- “Explore a ligand in PDB entry 1tqn and show its PDBe-reported interactions.”
- “Build a two-scene molecular story for PDB entry 1tqn, showing the protein
  first and then highlighting a ligand.”

See the [molecular workspace guide](docs/molecular-workspace.md) for setup,
tool examples, annotations, saved workspaces, updates, and host routing. The
Apps and aggregate servers also expose the `molview-spec` skill as MCP
resources for scene-building guidance.

### Data servers

| Server | Purpose |
| --- | --- |
| `all` | API, Search, Apps, and Graph tools through one server |
| `pdbe_api_server` | Entries, assemblies, molecules, ligands, publications, and validation data |
| `pdbe_search_server` | Solr searches with filtering, facets, grouping, and pagination |
| `pdbe_apps_server` | Interactive structure and ligand exploration, comparison, and MolViewSpec workspaces |
| `pdbe_graph_server` | PDBe-KB graph schema and queries against your local Neo4j database |

The recommended `all` server exposes API, Search, Apps, and Graph together.
Graph queries require your own PDBe-KB Neo4j database; PDBe does not provide a
public running instance. Configure individual server types if you only need a
subset of the tools.

## Quick start

Requires **Python 3.11+** and **[uv](https://github.com/astral-sh/uv)**.
Run directly from PyPI without a separate installation:

```bash
uvx pdbe-mcp-server
```

With no server type specified, this starts the aggregate `all` server over
stdio. To run only Search instead:

```bash
uvx pdbe-mcp-server --server-type pdbe_search_server
```

## Connect your AI client

For clients using a JSON `mcpServers` configuration, we recommend starting
with the aggregate server. It exposes the API, Search, Apps, and Graph tools
through one stdio connection:

```json
{
  "mcpServers": {
    "PDBe": {
      "command": "uvx",
      "args": ["pdbe-mcp-server", "--server-type", "all"]
    }
  }
}
```

Graph queries require your own PDBe-KB Neo4j database, and interactive Apps
views require an Apps-capable client.

If you only need selected servers, configure one or more individually:

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

Ensure `uvx` is in your client's PATH, then restart or reload the client.
Clients with a settings UI can use the same commands and arguments.

Try asking:

- “Find structures for UniProt accession P12345.”
- “Show structures released this month, grouped by experimental method.”
- “Find X-ray structures with resolution better than 2.0 Å.”

See [worked examples](examples/) for questions involving protein function,
ligand interactions, glycosylation, cryo-EM structures, and EMDB maps.

## Remote HTTP server

From a local checkout, start Streamable HTTP with:

```bash
uv run pdbe-mcp-remote-server --all
```

Connect to `http://127.0.0.1:8000/api/`, `/search/`, `/apps/`, or `/graph/`.
The `--all` flag also exposes `/all/`. Use `ROOT_PREFIX` for a path prefix.

See the [server reference](docs/server-reference.md) for Docker, legacy SSE,
search parameters, graph setup, and experimental TOON output.

## PDBe-hosted beta server

A beta-hosted remote MCP server is available at
[https://wwwdev.ebi.ac.uk/pdbe/mcp/all/](https://wwwdev.ebi.ac.uk/pdbe/mcp/all/).
Connect to it from an MCP client using Streamable HTTP. As a beta service, its
availability and interface may change. For beta-server issues or feedback,
email [pdbehelp@ebi.ac.uk](mailto:pdbehelp@ebi.ac.uk). For other issues, please
[open a GitHub issue](https://github.com/PDBeurope/PDBe-MCP-Servers/issues).

## Local development

Clone the repository and install dependencies:

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

Build the molecular UI with **Node.js 22.12+** before running the Apps server
or building a Python distribution:

```bash
cd apps/structure-explorer
npm ci
npm run build
cd ../..
```

For a local client connection, replace `uvx` with `uv` and use arguments like:

```json
["run", "--directory", "/path/to/PDBe-MCP-Servers", "pdbe-mcp-server", "--server-type", "pdbe_api_server"]
```

Rebuild the UI after UI changes. Python distributions include the generated
HTML artifacts. See [Development](DEVELOPMENT.md) for testing and packaging,
and [Contributing](CONTRIBUTING.md) for contribution guidance.

## Documentation and support

- [Molecular workspace guide](docs/molecular-workspace.md)
- [Server and tool reference](docs/server-reference.md)
- [Worked examples](examples/)
- [PDBe API documentation](https://www.ebi.ac.uk/pdbe/api/v2/)
- [PDBe-KB graph documentation](https://www.ebi.ac.uk/pdbe/pdbe-kb/graph)
- [Model Context Protocol](https://modelcontextprotocol.org/)
- [GitHub issues](https://github.com/PDBeurope/PDBe-MCP-Servers/issues)
- [PDBe Help & Support](https://www.ebi.ac.uk/about/contact/support/pdbe)

Licensed under [Apache 2.0](LICENSE).
