protein-blender-mcp

Style protein 3D structures in Blender by describing what you want in plain English.

"Fetch 4HHB, show the protein as a cartoon colored by chain, the hemes as sticks, put it on a white background and render it."

protein-blender-mcp is a Model Context Protocol server that connects an AI assistant such as Claude to Blender. It uses Molecular Nodes to import and draw structures. The assistant turns your words into tool calls like add_style(style="sticks", selection="resname HEM", color="element"). It then renders a preview to check the result, so you can keep refining in conversation.

You ──► Claude ──► protein-blender-mcp (MCP server) ──TCP:9877──► Blender add-on ──► Molecular Nodes

What you can ask for

• Load: fetch from the PDB (4HHB) or AlphaFold DB (UniProt ID), or open a local .pdb / .cif / .bcif / .sdf file

• Styles: cartoon, ribbon, surface, sticks, spheres, ball-and-stick, layered on any selection

• Selections: chains, residue ranges, ligands, binding pockets ("residues within 5 Å of ATP"), backbone, residue types

• Colors: by element, chain, rainbow (N→C), secondary structure, residue type, B-factor, AlphaFold pLDDT, Goodsell style, or any named / hex color

• Materials: default, ambient occlusion, flat, squishy, transparent

• Scene: background color or transparency, camera framing from front/back/top/…, EEVEE or Cycles, resolution

• Output: preview renders returned to the assistant, final PNG renders, saved .blend files

• Escape hatch: run arbitrary Blender Python for anything else (lighting, animation, node tweaks)

Related MCP server: Blender MCP

Requirements

• Blender 4.2 or newer (developed on 5.2)

• Molecular Nodes installed and enabled in Blender

• uv (recommended), or Python 3.10+

• An MCP client, such as Claude Desktop, Claude Code or Cursor

Installation

1. Install the Blender add-on

1. Download this repository and zip the addon/protein_blender_mcp folder, or run python scripts/build_addon.py, which writes dist/protein_blender_mcp.zip.

   Close every other Blender window before installing or updating any extension. Installing an extension makes Blender re-sync the shared Python packages used by all extensions, including Molecular Nodes' scipy, pandas and MDAnalysis. On Windows, a second running Blender keeps those files locked, so they get removed but not restored. Molecular Nodes then fails with errors like No module named 'databpy'. If that happens, close all Blender windows and install the zip again; the re-sync restores everything.

   You can also install from the command line (with Blender closed):

   blender --command extension install-file -r user_default -e dist/protein_blender_mcp.zip

2. In Blender, open Edit → Preferences → Get Extensions, click the ⌄ menu in the top right, and choose Install from Disk…. Select the zip.

3. In the 3D viewport, press N, open the Protein MCP tab, and click Start MCP Bridge.

2. Register the MCP server with your client

Claude Code

claude mcp add protein-blender -- uvx --from git+https://github.com/OmarArias-Gaguancela/protein-blender-mcp protein-blender-mcp

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "protein-blender": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/OmarArias-Gaguancela/protein-blender-mcp", "protein-blender-mcp"]
    }
  }
}

From a local clone

pip install -e .

Then use protein-blender-mcp as the command.

Set PROTEIN_BLENDER_PORT if you changed the port in the Blender panel.

Windows: Claude desktop app and uv

The Claude desktop app on Windows redirects files that programs it launches write under AppData into its own private folder. That breaks the folder links uv creates when it downloads a Python, giving errors like:

error: Missing expected target directory for Python minor version link at
`C:\Users\<you>\AppData\Roaming\uv\python\cpython-3.13...`

To fix it, store uv's Pythons outside AppData with UV_PYTHON_INSTALL_DIR, and pin Python 3.13:

claude mcp add --scope user protein-blender -e UV_PYTHON_INSTALL_DIR=C:\Users\<you>\.uv\python -- uvx --python 3.13 --from git+https://github.com/OmarArias-Gaguancela/protein-blender-mcp protein-blender-mcp

For Claude Desktop, add the same thing to the server entry:

"env": { "UV_PYTHON_INSTALL_DIR": "C:\\Users\\<you>\\.uv\\python" },
"args": ["--python", "3.13", "--from", "git+https://github.com/OmarArias-Gaguancela/protein-blender-mcp", "protein-blender-mcp"]

When you run claude mcp add from Windows PowerShell 5.1, PowerShell drops the -- separator and you get unknown option '--python'. Run the command from Git Bash, cmd, or PowerShell 7 instead.

Example prompts

• "Load 1EMA (GFP) as a cartoon colored rainbow from N to C terminus, with the chromophore as ball-and-stick."

• "Show 6VXX as a surface colored by chain, with a flat material on a black background."

• "Fetch AlphaFold model P69905 and color it by pLDDT confidence."

• "Zoom in on the binding pocket of 3HTB: residues within 5 Å of the ligand as sticks, everything else as a transparent cartoon."

• "Make the helices cylinders and the sheets flat, then render a 1920×1080 image with Cycles to ~/Desktop/figure.png."

Tools

Security note

The Blender add-on listens only on 127.0.0.1. The execute_blender_python tool runs whatever code the assistant sends, so only connect clients you trust. Stop the bridge from the panel when you're not using it.

Troubleshooting

• "Could not reach Blender": make sure Blender is open and the panel says Running on port 9877.

• "Molecular Nodes is not installed": install it from Get Extensions and enable it.

• Nothing visible after styling: ask the assistant to call get_scene_info and frame_camera. A selection may have matched no atoms.

License

MIT