Skip to content
Official

Molecular Analysis with Claude + RDKit MCP

Connect Claude Desktop to a local RDKit MCP server to calculate molecular formula, molecular weights, TPSA and Crippen descriptors from SMILES, with reproducible setup and acceptance checks.

Level: Intermediate Cost: Mixed Privacy: Cloud ~30 min
Start Setup
Follow

Public link：https://chemaiatlas.com/recipes/molecular-analysis-with-claude-rdkit/

You'll be able to

  • Calculate molecular formula and average/exact molecular weight from SMILES.
  • Calculate topological polar surface area and Crippen logP / molar refractivity.
  • Inspect tool calls and compare deterministic outputs with an acceptance baseline.

What you'll build

Scope

Claude Desktop provides the conversation and tool selection; TandemAI's RDKit MCP server performs calculations using RDKit. The server source is pinned to 3a7000ae62e94e095ecd804a403fca12982570cb (package 0.2.3; RDKit 2025.3.1). This recipe does not require PubChem or an OpenAI API key. Claude account access and any subscription charges are separate.

Environment and privacy

The upstream package declares Python >=3.10; the instructions select Python 3.11. Prepare Git, Python with venv/pip, and Claude Desktop with local MCP enabled. macOS and Windows setup is documented below. Linux server operation is separate from this desktop walkthrough. RDKit runs locally, but prompts and tool results are processed by Claude's cloud service. This is not a fully offline workflow.

Transport and tools

The server defaults to SSE; this recipe explicitly selects stdio. Only the five tools needed here are enabled. No server port is opened.

MCP bridge for Claude Desktop

RDKit MCP Server (TandemAI)

Cheminformatics calculation engine

RDKit

Stack Components

RDKit MCP Server (TandemAI)

MCP bridge for Claude Desktop · 0.2.3; commit 3a7000ae62e94e095ecd804a403fca12982570cb

Source installation pinned to the recorded commit; explicit stdio transport; five-tool allowlist.

Server and RDKit are open source; Claude account costs depend on the chosen plan.

View Resource

RDKit

Cheminformatics calculation engine · ==2025.3.1

Installed automatically by the MCP package as rdkit==2025.3.1; do not replace with an unpinned version in this environment.

Server and RDKit are open source; Claude account costs depend on the chosen plan.

View Resource

Compatibility

ClientOSArchitectureVersion requirements
Claude Desktop macOSarm64 / x64See component requirements
Claude Desktop Windowsx64See component requirements
Python macOSAny>= 3.10
Python WindowsAny>= 3.10
Python LinuxAny>= 3.10

Setup & Test

1. Prepare the desktop and Python environment

All platforms

Install Git, Python 3.11 and Claude Desktop. Confirm local MCP is permitted in your account or organization. Use a new directory for the clone. The shell commands in this recipe are instructions for the user; no installation has been performed.

Official source

Expected result

Git and Python are available; the installed Claude client allows local MCP.

2. Install the pinned server on macOS

macOS

Run in a terminal. Keep the checkout and virtual environment together; installation follows upstream pip install . with an isolated interpreter. Record the displayed dependency versions.

git clone https://github.com/tandemai-inc/rdkit-mcp-server.git
cd rdkit-mcp-server
git checkout 3a7000ae62e94e095ecd804a403fca12982570cb
python3.11 -m venv .venv
.venv/bin/python -m pip install .
.venv/bin/python -m pip show rdkit rdkit-mcp-server mcp
Official source

Expected result

Package installation completes; RDKit reports 2025.3.1 and server package reports 0.2.3.

3. Install the pinned server on Windows

Windows

Run in PowerShell. Use the virtual-environment Python directly; activating PowerShell scripts is unnecessary. If the Python launcher is unavailable, use the absolute path to your Python 3.11 interpreter.

git clone https://github.com/tandemai-inc/rdkit-mcp-server.git
cd rdkit-mcp-server
git checkout 3a7000ae62e94e095ecd804a403fca12982570cb
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install .
.\.venv\Scripts\python.exe -m pip show rdkit rdkit-mcp-server mcp
Official source

Expected result

Package installation completes; RDKit reports 2025.3.1 and server package reports 0.2.3.

4. Limit the exposed RDKit tools

All platforms

Save this YAML as recipe-settings.yaml in the cloned repository. Do not copy the upstream example unchanged: it contains overlapping allow/block examples. These names are checked in the tool wrappers. The allowlist also reduces the tool list exposed to the client.

ALLOW_LIST:
  - MolWt
  - ExactMolWt
  - CalcMolFormula
  - CalcTPSA
  - CalcCrippenDescriptors
BLOCK_LIST: []
Official source

Expected result

The saved YAML contains the five listed tools and an empty block list.

5. Connect Claude Desktop on macOS

macOS

In Claude Desktop open Settings > Developer > Edit Config. Merge this entry into the existing mcpServers object, preserving other servers. Replace every /ABSOLUTE/PATH with the actual full path. Config location: ~/Library/Application Support/Claude/claude_desktop_config.json. No shell expansion is assumed.

{
  "mcpServers": {
    "rdkit": {
      "command": "/ABSOLUTE/PATH/rdkit-mcp-server/.venv/bin/python",
      "args": [
        "/ABSOLUTE/PATH/rdkit-mcp-server/run_server.py",
        "--transport",
        "stdio",
        "--settings",
        "/ABSOLUTE/PATH/rdkit-mcp-server/recipe-settings.yaml"
      ]
    }
  }
}
Official source

Expected result

Valid JSON contains the absolute interpreter/script/settings paths and --transport stdio.

6. Connect Claude Desktop on Windows

Windows

In Claude Desktop open Settings > Developer > Edit Config. Merge this entry into the existing mcpServers object, preserving other servers. Replace C:\ABSOLUTE\PATH with the actual full path; JSON backslashes must be escaped. Config location: %APPDATA%\Claude\claude_desktop_config.json.

{
  "mcpServers": {
    "rdkit": {
      "command": "C:\\ABSOLUTE\\PATH\\rdkit-mcp-server\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\ABSOLUTE\\PATH\\rdkit-mcp-server\\run_server.py",
        "--transport",
        "stdio",
        "--settings",
        "C:\\ABSOLUTE\\PATH\\rdkit-mcp-server\\recipe-settings.yaml"
      ]
    }
  }
}
Official source

Expected result

Valid JSON contains escaped absolute Windows paths and --transport stdio.

7. Restart and inspect the connection

All platforms

Fully quit and reopen Claude Desktop. Inspect Developer connection status and the connector tool list; expect MolWt, ExactMolWt, CalcMolFormula, CalcTPSA and CalcCrippenDescriptors. If a tool approval is requested, review the SMILES argument. Do not separately start the default SSE server.

Official source

Expected result

The connector is connected and exposes all five selected tools.

8. Run the aspirin acceptance prompt

All platforms

Start a new chat with the RDKit connector enabled and paste this prompt. Inspect the actual tool calls; a text-only answer from model memory does not pass this check.

Use the rdkit connector to analyze aspirin with SMILES CC(=O)Oc1ccccc1C(=O)O. Call CalcMolFormula, MolWt, ExactMolWt, CalcTPSA and CalcCrippenDescriptors with this exact smiles argument. Report each actual tool result, its unit and tool name. Distinguish average molecular weight from monoisotopic mass; logP is a calculated descriptor, not a measured property. If a tool is unavailable or fails, state that explicitly and do not fill missing numbers from memory.
Official source

Expected result

Observed tool calls use the supplied SMILES. Formula C9H8O4; average mass about 180.159 g/mol (tolerance 0.02), monoisotopic mass about 180.04226 Da (tolerance 0.001), TPSA about 63.60 Ų (tolerance 0.1). CalcCrippenDescriptors returns approximately (1.3101, 44.7103) for logP and molar refractivity (tolerance 0.05). These are expected baselines, not results measured in this session.

9. Check invalid-input handling

All platforms

Submit this separate prompt. Accept an explicit tool error or a refusal to calculate after validation; never accept invented molecular properties for malformed input.

Use the RDKit tools to analyze SMILES not-a-smiles. Validate the input first. If it is invalid, report the validation or tool error and stop; do not invent molecular properties.
Official source

Expected result

Invalid SMILES is explicitly rejected; no formula or numeric descriptor is invented.

Troubleshooting

  • pip cannot find an RDKit wheel: check Python version and CPU architecture. This recipe targets Python 3.11; confirm RDKit 2025.3.1 has a wheel for your environment before proceeding. Preserve the pinned version or record a separate environment as unverified.
  • ModuleNotFoundError: verify that both installation and the Claude command use the same .venv Python. Do not use the system Python in the JSON.
  • Server missing / connection closes: check JSON syntax and absolute paths, including recipe-settings.yaml. Ensure --transport stdio is present. Use Developer logs; macOS: ~/Library/Logs/Claude; Windows: %APPDATA%\Claude\logs.
  • No tools registered / tool missing: check ALLOW_LIST spelling and ensure the five wrappers in the pinned source are listed. Save the YAML and fully restart Claude.
  • Property calculation fails: confirm the exact SMILES, selected tool and tool-call arguments. Invalid SMILES errors should not be bypassed by asking the model to guess.
  • Incorrect masses: distinguish MolWt from ExactMolWt. Check neutral aspirin, isotopes, charges and component versions before changing the baseline.
  • Cloud access or organization policy blocks use: this workflow requires Claude and allowed local MCP. Use the Python-only alternative below when that environment is unsuitable.
Still not working

Alternatives

For local calculations without a cloud conversation, use RDKit directly in Python: https://www.rdkit.org/docs/GettingStartedInPython.html . PubChem lookup is a separate enrichment workflow and is not required by this recipe. Do not treat RDKit descriptors as experimental properties.