Project Info
Problem: Protein design sits at the center of modern medicine — cancer immunotherapy, gene editing, next-generation antibodies all depend on it. It's also one of AI's fastest-growing applications: the U.S. AI protein design market is already valued around $420 million and projected to grow to $6–15 billion globally by 2030, accelerated by breakthroughs like AlphaFold. But the tooling hasn't kept pace. PyMOL is the de facto standard everyone in structural biology uses to visually inspect and analyze proteins, yet it requires memorizing dozens of terse text commands where even small mistakes (color red, chain A vs. chain A, color red) break the command. Working scientists lose real time every day looking up syntax, manually inspecting designs for errors, and cross-checking outputs by hand — time that should go toward the actual science. Our solution: NovoProteinAI lets you control PyMOL using plain English instead of memorized commands, so you can move from question to answer fluidly instead of wasting hours on syntax-wrangling. You type something like "highlight the binding interface between chain A and chain B" or "show me the epitope this antibody is targeting" — and an AI agent does the rest. It interprets your request, pulls in relevant research from scientific papers that would’ve required a large investment in time, and runs the correct sequence of PyMOL commands to generate the visualization instantly. It also acts as an automated QC and analysis layer. It checks that what you designed is what actually came out, for example verifying the design is the right format (antibody, nanobody, scFv) and confirming it's actually targeting the epitope you specified. This catches mismatches before they cost you a wasted design cycle. It can compare multiple design outputs side by side, flagging clashes, measuring interface size, and scoring quality, with a plain-language readout of what each metric means so you can make a faster call on which design to move forward with. This isn't a simplified or training-wheels version of the tool — it's the same PyMOL power, accessed faster, with automated checks layered on top that catch errors a human might miss on a manual pass. The result: less time fighting tool syntax and manually inspecting structures, more time iterating on designs — more designs reviewed per day, fewer costly mistakes carried forward. Architecture
How we built it
: Fetch.ai uAgents — agent lives on Agentverse, reachable by anyone on the network via the ACP Chat Protocol (UI) PyMOL MCP Bridge — FastMCP server over stdio bridges the agent to a TCP plugin running inside PyMOL, enabling real-time command execution Claude Code — Vibe-coding Tools, LLM for understanding the user input from Agentverse Redis — the key to understanding research papers, whether they are uploaded by the user or found by the AI Agent, is implemented with a RAG pipeline utilizing Redis’ Vector Database Cognition (Devin) — The hero to our vibe-coding journey RunPod — for deploying the virtual machine hosting PyMOL
Challenges we ran into
: Agentverse: ACP Chat Protocol has two layers — uAgents messaging and the Agentverse Chat Protocol are separate. Every message needs an acknowledgement first, and replies must use TextContent — miss either and Agentverse silently drops the message. Agentverse needs 10 interactions before the agent goes live — wrote trigger_interactions.py to send test messages automatically, which also worked as a smoke test. Public URL breaks when ngrok restarts — every new ngrok URL means re-running register_agent.py. No auto-update. Chat protocol compliant — other agents and users can interact via standard UI Regex parser broke on natural word order: color red, chain A vs. chain A, color red is the same but when i send to PyMOL MCP, it is the same so that I use Redis: We had some connection issues with Redis Cloud, so we decided to pivot to a local Redis vector database. This removed the wifi connection variable, which could have impacted our ability to connect to the cloud consistently. Ensuring that the embeddings did not split vital information between two chunks was another challenge. To address this issue, we implemented a regex and semantic chunking to ensure that the content of each chunk was split at logical points in the text. We wanted to have both the context of the chunk and the PDB ID (which is the code that refers to a specific protein structure). We separated this process into two steps: run Redis’ vector search that uses cosine similarity to retrieve a relevant chunk, and then use that chunk’s paper ID to locate the PDB ID in the paper.
Accomplishments we're proud of
: Bridging interdisciplinary skills together to create a working product. Enabling non-biologist to load, color, and render a real protein structure in under 30 seconds with zero biology knowledge Implement a complete, working RAG-pipeline Implement an MCP server for PyMOL that our AI Agent can connect to
What we learned
: MCP is a clean abstraction layer between AI and tools, the agent never needs to know how PyMOL works internally. Fetch.ai's agent network changes what "deployed" means: once the agent is on Agentverse, anyone on the network can reach it without any client setup, API keys, or SDKs on their end. Distribution is built into the infrastructure. Vibe-coding tools like Claude Code or Devin is real but require direction from the user, user now is like a product designer, thinking more about the product than normal coding Scope fast, cut faster — a hackathon forces you to decide what's core and what's nice-to-have within hours. The hardest part isn't the code — it's the integration between systems. Each piece worked in isolation. Getting them to talk to each other reliably was where most time went.
What's next
: We want to continue this path of making protein-design accessible to the general public, much like how vibe-coding is starting to become more and more accessible. Currently, we have the research and visualization parts of the protein development process built. We intend to continue to add tools and features like incorporating the RFDiffusion model and protein ESMFold to give user the end-to-end experience of protein development.
NovoProteinAI
A tool that uses PyMOL as typed tools to LLM agents like Claude Desktop, Cline, and Devin using MCP and pymol plugin
Architecture
Claude/Devin (MCP client)
↕ stdio
FastMCP Server (pymol_mcp/)
↕ TCP (localhost:9877, JSON-RPC 2.0)
PyMOL Plugin (pymol_plugin/)
↕ PyMOL API
PyMOL Session
The bridge consists of two components:
- PyMOL Plugin - TCP server running inside PyMOL that executes commands
- MCP Server - FastMCP server that exposes PyMOL functionality as MCP tools
Features
- 🔌 5 Core Tools: Load structures, select atoms, color, render images, health check
- 🔄 Auto-reconnect: Exponential backoff retry logic
- ⚙️ Configurable: Environment variables or YAML config file
- 🛡️ Error Handling: Comprehensive error handling and logging
- 📡 JSON-RPC 2.0: Length-prefixed wire protocol over TCP
Installation
1. Install MCP Server
cd NovoProteinAI
pip install -e .
2. Install PyMOL Plugin
See PLUGIN_INSTALL.md for detailed instructions.
Quick method:
- Open PyMOL
- Go to
Plugin→Plugin Manager - Click
Install New Plugin→Choose file... - Select
pymol_plugin/__init__.py - Click
OKto install
3. Configure MCP Client
See MCP_CONFIG.md for client-specific configuration.
For Claude Desktop, add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"pymol": {
"command": "python",
"args": ["-m", "pymol_mcp.server"],
"env": {
"PYMOL_HOST": "localhost",
"PYMOL_PORT": "9877"
}
}
}
}
Usage
1. Start PyMOL Plugin
- Open PyMOL
- Go to
Plugin→agentic-pymol plugin→Control Panel - Click Start Server and watch the live status + activity log
2. Use from LLM Agent
The MCP server exposes 5 tools:
load_structure
Load a molecular structure from file or PDB ID.
load_structure(source="/path/to/protein.pdb")
load_structure(source="1ABC", object_name="my_protein")
select_atoms
Create a named selection of atoms.
select_atoms(selection_name="active_site", selection_expr="resi 100-150")
select_atoms(selection_name="backbone", selection_expr="name CA+C+N+O")
color_selection
Apply color to a selection.
color_selection(color="red", selection="chain A")
color_selection(color="blue") # colors all
render_image
Save an image of the current view.
render_image(output_path="/tmp/protein.png", width=1920, height=1080)
render_image(output_path="/tmp/hq.png", ray_trace=True)
ping_pymol
Check connection and get PyMOL version.
ping_pymol()
Research Agent (Fetch.ai / Agentverse)
src/research_agent.py is a Fetch.ai uAgent that turns a plain-English
vaccine/therapeutic goal into a structured target result sourced from public
biology databases (RCSB PDB + PubMed). Its JSON output matches the inputs of
render_image() in visualize.py.
Output contract
{
"target_name": "SARS-CoV-2 spike receptor-binding domain",
"pdb_id": "6VXX",
"chain": "A",
"epitope_residues": [417, 484, 501],
"binder_pdb_ids": ["7K8M"],
"explanation": "Plain-English summary a non-biologist can follow.",
"citations": [{"title": "...", "pmid": "...", "url": "https://pubmed.ncbi.nlm.nih.gov/..."}]
}
Run it
pip install -r requirements.txt
export AGENT_SEED="some-fixed-phrase" # required: stable agent address
export ASI_ONE_API_KEY="..." # optional: falls back to keyword parsing
python src/research_agent.py
Register on Agentverse
- Run the agent — it prints an Agentverse Inspector/mailbox link.
- Sign in at agentverse.ai and connect the mailbox so the agent is reachable without a public IP.
publish_manifest=Trueadvertises chat capability, making it discoverable from ASI:One.- Test by messaging the agent:
build a vaccine for COVID.
Environment variables
AGENT_SEED— fixed seed phrase for a stable agent address (required to run).ASI_ONE_API_KEY— ASI:One key for goal parsing + explanation drafting (optional).
Note:
epitope_residuesis currently returned empty (IEDB lookup is a planned follow-up).
Configuration
Environment Variables
PYMOL_HOST- PyMOL plugin host (default:localhost)PYMOL_PORT- PyMOL plugin port (default:9877)PYMOL_TIMEOUT- Request timeout in seconds (default:30.0)PYMOL_RECONNECT_ATTEMPTS- Number of reconnection attempts (default:3)PYMOL_RECONNECT_DELAY- Initial reconnection delay in seconds (default:1.0)PYMOL_LOG_LEVEL- Logging level (default:INFO)
Configuration File
Create config.yaml:
host: localhost
port: 9877
timeout: 30.0
reconnect_attempts: 3
reconnect_delay: 1.0
log_level: INFO
Run with config file:
python -m pymol_mcp.server --config config.yaml
Development
Project Structure
NovoProteinAI/
├── pymol_plugin/
│ └── __init__.py # PyMOL plugin (TCP server)
├── pymol_mcp/
│ ├── __init__.py
│ ├── server.py # FastMCP server entry point
│ ├── client.py # TCP client for PyMOL
│ ├── config.py # Configuration management
│ └── tools.py # MCP tool definitions
├── tests/
│ ├── test_protocol.py
│ ├── test_client.py
│ └── test_tools.py
├── src/ # Chat interface
├── requirements.txt
├── pyproject.toml
└── README.md
Running Tests
pip install -e ".[dev]"
pytest tests/
Manual Testing
# Terminal 1: Start PyMOL and enable plugin
pymol
# In PyMOL: Plugin → agentic-pymol plugin → Control Panel → Start Server
# Terminal 2: Test MCP server
python -m pymol_mcp.server
Wire Protocol
The bridge uses JSON-RPC 2.0 over TCP with length-prefixed messages:
[4-byte big-endian length][JSON payload]
Example request:
{
"jsonrpc": "2.0",
"method": "load_structure",
"params": {"source": "1ABC"},
"id": 1
}
Example response:
{
"jsonrpc": "2.0",
"result": {"message": "Loaded structure: 1ABC", "object_name": "1ABC"},
"id": 1
}
Troubleshooting
Connection Refused
- Ensure PyMOL is running
- Verify plugin is started:
Plugin→agentic-pymol plugin→Server Status - Check port is not in use:
lsof -i :9877
Plugin Not Loading
- Check PyMOL console for errors
- Verify Python version compatibility (≥3.8)
- Try reinstalling plugin
MCP Server Not Responding
- Check logs for connection errors
- Verify configuration (host/port)
- Test connection:
telnet localhost 9877
License
MIT
Contributing
Contributions welcome! Please open an issue or PR.
Analysis
View
Metric
- 6
- 3
- 1
Figures cover GitHub contributors during the hackathon window. A co-authored commit counts in full for each author, so per-member totals add up to more than the whole-team figures.
Technology
- PythonIn code
- RedisClaimed
1 of 2 appear in the indexed code. 1 claimed on Devpost could not be matched to code, which may simply mean the tool leaves no trace in the repository.
AI coding agents
- Claude CodeCommits
Detected from committed agent config files and commit authorship. Absence of a signal is not proof an agent was unused.
Codebase size
Source size
144 KB
Source files
26
Counts recognized source files only; vendored directories, binaries and lockfiles are excluded, so this is smaller than the repository on disk.
Repository
santosrai/NovoProteinAI
36 files · 477 KB · @ b219c62
Structure
Application logic
15 files · 42%Domain rules, services and shared utilities.
Supporting
Layers are inferred from where files sit in the tree, not from reading the code. A project that names its directories unconventionally will read oddly here — open the file browser to check anything the diagram implies.
Languages
- Python69%
- Markdown29%
- Shell1%
Share of indexed source by file size. Binary and vendored files are excluded.
Dependencies
requirements.txt
pypi · 10- fastmcp
- langchain-anthropic
- langchain-core
- langchain-mcp-adapters
- langgraph
- python-dotenv
- pyyaml
- requests
- uagents
- uagents-core
pyproject.toml
pypi · 4- fastmcp
- pyyaml
- +2 more
Declared in the repository’s manifests at the indexed commit. A declared package is not proof it is used, and runtime dependencies are listed first.
Export this project's context (description, README, evidence, key source files) to chat with an AI agent elsewhere.