---

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, 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), 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), 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

• 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

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

2. Build the Docker image

docker buildx build --load -t posebusters-mcp-server .

3. Run the container

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

# 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)

# 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)

# 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:

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

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

# 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 by Martin Buttenschoen (© 2023),
licensed under the BSD 3-Clause License.
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.