Organic Chemistry Structure MCP Server 🧪

A production-quality Model Context Protocol (MCP) Server designed to allow AI assistants (ChatGPT, Gemini, Claude, Cursor, MCP Inspector) to deterministically render, resolve, and display accurate 2D organic chemistry structures, reactions, mechanisms, resonance contributors, and stereochemistry directly inside AI conversations using native MCP image content.

Key Features

• Direct In-Chat 2D Depictions: Returns native MCP image content items (image/png base64) so compatible AI clients render structures directly without requiring an external image host or diffusion model.

• Deterministic Chemical Rendering: Powered by RDKit and Cairo for publication-quality textbook depictions with CPK standard colors and clear skeletal bonds.

• Multi-Tier Resolution:

  1. Curated JEE Presets: 200+ Class 11/12 JEE Main and Advanced compounds and reagents loaded locally for instantaneous (<10ms) responses.

  2. SQLite Persistent Cache: Auto-caches resolved compounds and pre-rendered depictions.

  3. PubChem PUG REST API: Fallback lookup for thousands of known organic molecules.

  4. Ambiguity Engine: Never guesses isomers. Flags ambiguous names (e.g. cresol, butanol, xylene) and prompts for disambiguation.

• 7 MCP Tools:

  • show_structure: Visual 2D depiction with formula, MW, SMILES, and source metadata.

  • resolve_compound: Complete molecular metadata in structured JSON.

  • show_reaction: Publication-quality aligned reaction equations with conditions and arrows.

  • show_mechanism: Multi-step mechanisms with intermediate panels, formal charges, and curved arrows (SN1, SN2, EAS, Alkene Hydration, Aldol).

  • compare_structures: Side-by-side molecular comparison grids.

  • show_resonance: Resonance canonical contributors enclosed in brackets with $\leftrightarrow$ arrows.

  • show_stereochemistry: Explicit 3D wedge-and-dash projections with R/S and E/Z annotations.

• Dual Transports:

  • Streamable HTTP: Modern /mcp endpoint for remote AI connections.

  • Stdio: Standard input/output transport for local AI tools and MCP Inspector CLI.

• Testing & Admin Web Studio: Built with React + Vite + Tailwind CSS for live testing, inspecting MCP calls, browsing presets, and monitoring server health.

Related MCP server: ChemCP

Quick Start

1. Prerequisites

• Node.js: v18+ (tested on Node.js v24)

• Python: v3.10+ (tested on Python 3.12 with .venv)

2. Installation

# Clone or open the repository directory
cd chem

# Install Node.js dependencies
npm install

# Setup Python virtual environment and chemistry dependencies
py -3.12 -m venv .venv
.\.venv\Scripts\python -m pip install rdkit pillow fastapi uvicorn pydantic requests pytest

3. Build & Run

# Build the TypeScript backend & React frontend
npm run build
cd web && npm run build && cd ..

# Start the unified MCP server & Web Studio (starts Node and Python engine automatically)
npm run dev
# Or for production:
npm start

• MCP Streamable HTTP Endpoint: http://localhost:3000/mcp

• Web Testing & Admin Studio: http://localhost:3000/

• Healthcheck: http://localhost:3000/health

Live Deployment & AI Connection

• Live Web Dashboard: https://chem-ten-dun.vercel.app/

• Live Streamable HTTP MCP Endpoint: https://chem-ten-dun.vercel.app/mcp

Connecting to AI Clients

1. Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "organic-chemistry": {
      "url": "https://chem-ten-dun.vercel.app/mcp"
    }
  }
}

2. Cursor IDE & Cline

In .cursor/mcp.json or Settings $\rightarrow$ MCP:

{
  "mcpServers": {
    "organic-chemistry": {
      "url": "https://chem-ten-dun.vercel.app/mcp"
    }
  }
}

3. Master AI System Prompt (ChatGPT / Claude / Gemini)

Paste the following prompt into your Custom GPT instructions, Claude Project, or System Prompt:

You are an expert Organic Chemistry AI Assistant integrated with the Organic Chemistry Structure MCP Server (https://chem-ten-dun.vercel.app/mcp).
Whenever explaining chemical compounds, reactions, mechanisms, resonance, comparisons, or stereochemistry, PROACTIVELY CALL the MCP tools:
- show_structure: { "compound": "..." }
- show_reaction: { "reactants": ["..."], "products": ["..."], "conditions": "..." }
- show_mechanism: { "reaction": "..." }
- compare_structures: { "compounds": ["...", "..."] }
- show_resonance: { "compound": "..." }
- show_stereochemistry: { "compound": "...", "configuration": "R" | "S" }

Running Tests

# Run Node.js unit and integration tests (Vitest)
npm test

# Run Python RDKit engine tests (pytest)
npm run test:python

License

MIT