Ketcher Server

MCP (Model Context Protocol) server for Ketcher chemical structure editor integration with Claude.

Features

• 🧪 Open Ketcher Editor: Launch Ketcher web interface in browser
• 🔄 Format Conversion: Convert between SMILES, MOL, InChI formats
• 🖼️ Image Generation: Generate PNG/SVG images from SMILES
• 📊 Molecular Properties: Calculate molecular weight, LogP, TPSA, etc.
• ✅ Validation: Validate SMILES strings

Installation

Prerequisites

• Python 3.10 or higher (tested with Python 3.11)
• pip

Note: If you're using macOS with system Python 3.9, you'll need to install Python 3.10+ separately:

# Using Homebrew
brew install [email protected]

# Verify installation
/opt/homebrew/bin/python3.11 --version

Install Dependencies

cd ketcher-mcp-server

# If using Python 3.11 from Homebrew
/opt/homebrew/bin/python3.11 -m pip install -e .

# Or if python3 is already 3.10+
pip install -e .

For Development

pip install -e ".[dev]"

Usage

Running the Server

python -m ketcher_mcp.server

Or use with mcp CLI:

mcp run ketcher_mcp.server

Configuration for Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "ketcher": {
      "command": "/opt/homebrew/bin/python3.11",
      "args": ["-m", "ketcher_mcp.server"]
    }
  }
}

Note: Adjust the Python path based on your installation:

• Homebrew Python 3.11: /opt/homebrew/bin/python3.11
• System Python 3.10+: python3 or python3.10
• Check your path with: which python3.11

On macOS, the config file is located at:

~/Library/Application Support/Claude/claude_desktop_config.json

Available Tools

1. open_ketcher

Opens Ketcher chemical structure editor in your default web browser.

Example:

Open Ketcher editor

2. smiles_to_image

Converts SMILES notation to molecular structure image.

Parameters:

• smiles (str): SMILES notation
• width (int, optional): Image width (default: 400)
• height (int, optional): Image height (default: 300)
• format (str, optional): 'png' or 'svg' (default: 'png')

Example:

Generate image for aspirin: CC(=O)Oc1ccccc1C(=O)O

3. smiles_to_mol

Converts SMILES to MOL file format.

Parameters:

• smiles (str): SMILES notation

Example:

Convert CC(=O)Oc1ccccc1C(=O)O to MOL format

4. mol_to_smiles

Converts MOL file format to SMILES.

Parameters:

• mol_block (str): MOL file content

5. get_molecule_properties

Calculates molecular properties from SMILES.

Parameters:

• smiles (str): SMILES notation

Returns:

• Molecular formula
• Molecular weight
• Number of atoms, bonds, rings
• LogP, TPSA
• Hydrogen bond donors/acceptors
• Rotatable bonds

Example:

Get properties of caffeine: CN1C=NC2=C1C(=O)N(C(=O)N2C)C

6. validate_smiles

Validates a SMILES string.

Parameters:

• smiles (str): SMILES notation to validate

Example:

Validate SMILES: CCO

7. smiles_to_inchi

Converts SMILES to InChI identifier.

Parameters:

• smiles (str): SMILES notation

8. smiles_to_inchikey

Converts SMILES to InChIKey identifier.

Parameters:

• smiles (str): SMILES notation

Example Workflows

Workflow 1: Draw and Analyze a Molecule

1. "Open Ketcher editor"
2. Draw your molecule in Ketcher
3. Copy the SMILES from Ketcher
4. "Get properties of [SMILES]"
5. "Generate image for [SMILES]"

Workflow 2: Convert Chemical Formats

1. "Convert aspirin SMILES to MOL format: CC(=O)Oc1ccccc1C(=O)O"
2. "Convert this MOL to InChI"
3. "Generate InChIKey"

Workflow 3: Validate and Visualize

1. "Validate SMILES: CCO"
2. "Generate SVG image for CCO"
3. "Get molecular properties"

Technical Details

Architecture

• FastMCP: MCP server framework
• RDKit: Chemical informatics library for molecule processing
• Ketcher: Web-based chemical structure editor (via CDN)

Supported Formats

• SMILES: Simplified Molecular Input Line Entry System
• MOL: MDL Molfile format
• InChI: IUPAC International Chemical Identifier
• InChIKey: Hashed InChI for database lookups
• PNG/SVG: Image formats for visualization

Troubleshooting

RDKit Installation Issues

If you encounter issues installing RDKit:

# Using conda (recommended)
conda install -c conda-forge rdkit

# Or using pip
pip install rdkit-pypi

Ketcher Not Opening

Make sure you have a default web browser configured. The server uses Python's webbrowser module.

Development

Running Tests

pytest

Project Structure

ketcher-mcp-server/
├── ketcher_mcp/
│   ├── __init__.py
│   └── server.py
├── pyproject.toml
└── README.md

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

MIT License

Acknowledgments

• Ketcher - EPAM's open-source chemical structure editor
• RDKit - Open-source cheminformatics toolkit
• FastMCP - Fast MCP server framework

Version History

• 0.1.0 (2026-03-09): Initial release
  • Basic SMILES/MOL conversion
  • Image generation
  • Molecular property calculation
  • Ketcher integration