---
title: Posebusters MCP Server
emoji: 😻
colorFrom: gray
colorTo: pink
sdk: gradio
sdk_version: 5.36.2
app_file: app.py
pinned: false
license: bsd-3-clause
short_description: 'MCP server for PoseBusters: validates ligand–protein struct'
---

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference


# 🧪 PoseBusters MCP Server
<img width="1536" height="1024" alt="image" src="https://github.com/user-attachments/assets/5f4e0750-9168-4963-b8cd-1b7ec9892cef" />

This Hugging Face Space provides an **MCP-compatible API** around [PoseBusters](https://github.com/maabuu/posebusters), a command-line tool for validating the **physical and chemical plausibility** of molecular docking poses.

> **⚠️ Disclaimer**  
> This project is unofficial and not affiliated with or endorsed by the original author of PoseBusters.

---

## ✅ Features

✅ **Supports molecular file uploads**  
Accepts ligand files (`.sdf`) and protein structures (`.pdb`) via either:
- a simple web interface (Gradio tab UI), or  
- HTTP POST requests using `multipart/form-data`.

🔁 **Redocking validation (optional)**  
If a crystal ligand (`.sdf`) is provided, the API performs redocking validation by comparing it to the predicted ligand pose.

⚙️ **Leverages the `bust` CLI from PoseBusters**  
Internally, this server uses the PoseBusters command-line tool to evaluate:
- pose plausibility  
- chemical validity  
- geometry checks  

📊 **Structured JSON responses**  
The output follows the [Model Context Protocol (MCP)](https://modelcontextprotocol.io), making it easy to use results in:
- UI panels  
- workflows  
- logic pipelines  

🤖 **MCP-Compatible API (for use in AI workflows)**  

This project is fully **MCP-compliant**, meaning it follows the [Model Context Protocol (MCP)](https://modelcontextprotocol.io), the standard for exposing tools in AI-driven workflows and UIs.

- ✅ Exposes a valid `GET /mcp/context` for tool discovery and UI generation.
- ✅ Accepts `POST /mcp/predict` with `multipart/form-data` for structured tool execution.
- ✅ Returns results in structured JSON, ready for use in agents, chatbots, or pipelines.
- ✅ When deployed on your own **Hugging Face Spaces**, it works as an **MCP server** that can be added to your toolset from the MCP badge.

*🧠 What does this mean for you?*

If you're using **VSCode with Hugging Face MCP**, **Claude**, or **any other MCP-compatible client**, you can:

- 🔹 Add this tool directly from its Space card using the MCP badge.
- 🔹 Interact with it using standard UI panels or programmatic workflows.
- 🔹 Submit files like `.sdf` and `.pdb` and receive validated pose results.

*Notes*

- The app runs perfectly inside a **Gradio Space** or a Docker container, using `FastAPI` as its backend.
- The app is **fully MCP-compatible** and **discoverable** once deployed.
- You can host it on your own infrastructure, or push it to Spaces for instant integration into MCP-enabled environments.

---

## 🤗 How to Use (in Hugging Face Space)

👉 **Space UI**: [https://huggingface.co/spaces/lepanto1571/posebusters-mcp-server](https://huggingface.co/spaces/lepanto1571/posebusters-mcp-server)

- Upload your `.sdf` ligand and `.pdb` protein files
- (Optional) Add a `.sdf` with the ''true'' crystal ligand
- Click on **Submit**
- Results will appear in the interactive table

---

## 🐳 Run Locally with Docker
### 1. Clone the repository

```bash
git clone https://github.com/lepanto1571/posebusters-mcp-server.git
cd posebusters-mcp-server
```

### 2. Build the Docker image

```bash
docker buildx build --load -t posebusters-mcp-server .
```
### 3. Run the container

```bash
docker run -p 7860:7860 posebusters-mcp-server
```
The server will start on http://localhost:7860.

---

## ⚙️ How to Use the API (MCP-compatible)

### 🔎 1. Discover API via MCP Context

```bash
# Using curl
curl -X GET http://localhost:7860/mcp/context

# Using Python
import requests
response = requests.get("http://localhost:7860/mcp/context")
context = response.json()
```

### 2. Run validation (ligand + protein)

```bash
# Using curl
curl -X POST http://localhost:7860/mcp/predict \
  -F action=validate_pose \
  -F ligand_input=@ligand.sdf \
  -F protein_input=@protein.pdb

# Using Python
import requests

files = {
    'ligand_input': ('ligand.sdf', open('ligand.sdf', 'rb')),
    'protein_input': ('protein.pdb', open('protein.pdb', 'rb'))
}
data = {'action': 'validate_pose'}

response = requests.post(
    "http://localhost:7860/mcp/predict",
    files=files,
    data=data
)
results = response.json()
```

### 3. Run redocking validation (ligand + crystal + protein)

```bash
# Using curl
curl -X POST http://localhost:7860/mcp/predict \
  -F action=redocking_validation \
  -F ligand_input=@ligand.sdf \
  -F protein_input=@protein.pdb \
  -F crystal_input=@crystal.sdf

# Using Python
import requests

files = {
    'ligand_input': ('ligand.sdf', open('ligand.sdf', 'rb')),
    'protein_input': ('protein.pdb', open('protein.pdb', 'rb')),
    'crystal_input': ('crystal.sdf', open('crystal.sdf', 'rb'))
}
data = {'action': 'redocking_validation'}

response = requests.post(
    "http://localhost:7860/mcp/predict",
    files=files,
    data=data
)
results = response.json()
```

### Response Format

All responses follow the MCP standard format:

```python
{
    "object_id": "validation_results",
    "data": {
        "columns": ["ligand_id", "status", "passed/total", "details"],
        "rows": [
            ["mol1", "✅", "8/8", "All tests passed"],
            # ... more results
        ]
    }
}
```

### Error Handling

The API uses standard HTTP status codes:
- 200: Success
- 400: Invalid request (wrong file type, missing required files)
- 500: Server error (validation failed, internal error)

Error responses include detailed messages:
```python
{
    "object_id": "validation_results",
    "data": {
        "columns": ["ligand_id", "status", "passed/total", "details"],
        "rows": [
            ["unknown", "❌", "0/0", "Detailed error message"]
        ]
    }
}
```

## 🧪 Development and Testing

### Running Tests

Tests can be run directly using Docker:

```bash
# Run tests with verbose output
docker run posebusters-mcp-server pytest -v

# Run tests with coverage report
docker run posebusters-mcp-server pytest --cov=. --cov-report=term-missing
```

### Validation

The API uses JSON Schema validation for:
- MCP Context (`/mcp/context`)
- Prediction Responses (`/mcp/predict`)
- File Types (MIME validation)

Schema definitions are in `schema.py`.

---

## 📚 Documentation & Citation
### 📖 PoseBusters documentation:
Full usage and command-line reference available at
https://posebusters.readthedocs.io/en/latest

### 🧾 Scientific paper:
Martin Buttenschoen, Andreas Bender (2023). "PoseBusters: a consistency check for 3D protein–ligand binding poses".
Read it on arXiv: https://arxiv.org/abs/2308.05777

### 💡 If you use this server or PoseBusters in your work, consider citing the original paper.

---

## 📄 License & Credits

This project uses [PoseBusters](https://github.com/martin-btw/posebusters) by Martin Buttenschoen (© 2023),  
licensed under the [BSD 3-Clause License](https://opensource.org/licenses/BSD-3-Clause).  
A full copy of the original license is available at: `third_party/posebusters/LICENSE`.

This service is an **independent wrapper** and is **not affiliated with or endorsed by** the original author.