SMILES Visualizer MCP Server

A Model Context Protocol (MCP) server for molecular visualization using SMILES (Simplified Molecular Input Line Entry System) strings. This server provides multiple visualization approaches for chemical structures including RDKit, NetworkX, Plotly, and custom matplotlib visualizations.

Features

• Multiple Visualization Types: RDKit 2D structures, network graphs, interactive Plotly charts, and custom matplotlib visualizations

• Molecular Information: Detailed molecular properties and descriptors

• SMILES Validation: Built-in validation using RDKit

• Batch Processing: Process multiple SMILES strings at once

• HTTP Streamable Transport: Modern MCP transport for easy integration

• Base64 Image Output: Images returned as base64 strings for easy embedding

Available Tools

Core Tools

1. validate_smiles - Validate SMILES strings using RDKit

2. get_molecular_info - Get detailed molecular information and properties

3. visualize_rdkit - Create RDKit 2D molecular visualizations

4. visualize_network - Create network graph visualizations

5. visualize_plotly - Create interactive Plotly visualizations

6. visualize_custom_matplotlib - Create custom matplotlib visualizations

7. compare_visualizations - Generate all visualization types for comparison

8. batch_visualize - Process multiple SMILES strings

Debug/Development Tools

9. store_plotly_json - Store Plotly JSON visualizations for debugging/development

10. get_stored_plotly_json - Retrieve stored Plotly JSON with optional base64 encoding

11. list_stored_plotly_keys - List all stored Plotly JSON keys

12. clear_stored_plotly_data - Clear all stored Plotly JSON data

13. convert_to_image - Convert any content to ImageContent with specified mime type and encoding

Molecular Properties

The server calculates various molecular properties including:

• Molecular weight

• Number of atoms, bonds, and rings

• Molecular formula

• LogP and molar refractivity

• Topological polar surface area (TPSA)

• Number of rotatable bonds

• Hydrogen bond donors/acceptors

Debug/Development Tools Usage

The debug tools are designed for development and testing purposes:

store_plotly_json

• Purpose: Store Plotly JSON visualizations for later retrieval

• Parameters:

  • smiles: SMILES string as identifier

  • plotly_json: JSON string containing Plotly figure data

  • encode_base64: Boolean to control base64 encoding (default: True)

• Use Case: Store generated visualizations for debugging or batch processing

get_stored_plotly_json

• Purpose: Retrieve stored Plotly JSON visualizations

• Parameters:

  • smiles: SMILES string identifier

  • encode_base64: Boolean to control output format (default: True)

• Returns:

  • When encode_base64=True: ImageContent with application/vnd.plotly.v1+json mimetype

  • When encode_base64=False: TextContent with raw JSON data

• Use Case: Retrieve stored visualizations for display or further processing

list_stored_plotly_keys

• Purpose: List all stored Plotly JSON identifiers

• Use Case: Check what visualizations are available in storage

clear_stored_plotly_data

• Purpose: Clear all stored Plotly JSON data

• Use Case: Reset storage for testing or cleanup

convert_to_image

• Purpose: Convert any content to ImageContent with specified mime type and encoding

• Parameters:

  • content: String content to convert (required)

  • mime_type: MIME type for the ImageContent (default: "smiles_seq")

  • encode_base64: Boolean to control base64 encoding (default: True)

• Returns:

  • When encode_base64=True: ImageContent with base64 encoded data

  • When encode_base64=False: ImageContent with plain text data

• Use Case: Convert any text content (SMILES, JSON, etc.) to ImageContent format for consistent handling

Installation

Prerequisites

• Python 3.8 or higher

• RDKit (for molecular processing)

• Matplotlib (for custom visualizations)

• NetworkX (for network graphs)

• Plotly (for interactive visualizations)

Setup

1. Clone or download the project

2. Install dependencies:

Or using uv (recommended):

Quick Start

Option 1: Direct Installation

1. Install dependencies

   pip install -r requirements.txt

2. Run the server

   python server.py --host 127.0.0.1 --port 8080 --verbose

Option 2: Using uv (Recommended)

1. Install dependencies with uv

   uv pip install -r requirements.txt

2. Run the server

   python server.py --host 127.0.0.1 --port 8080 --verbose

Option 3: Development Mode (Linux/macOS)

1. Make entrypoint script executable

   chmod +x dev_entrypoint.sh

2. Run with development entrypoint

   ./dev_entrypoint.sh

Option 4: Docker

1. Build and run with Docker Compose

   docker-compose up -d

2. Or build manually

   docker build -t smiles-visualizer-mcp . docker run -p 8080:8080 smiles-visualizer-mcp

3. Run with custom environment variables

   docker run -p 8080:8080 \ -e MCP_HOST=0.0.0.0 \ -e MCP_PORT=8080 \ -e VERBOSE=true \ -e OUTPUT_DIR=/app/output \ smiles-visualizer-mcp

Usage

Running the Server

Start the MCP server with HTTP Streamable transport:

Command Line Options

• --host, -H: Host address (default: 127.0.0.1)

• --port, -p: Port number (default: 8080)

• --output-dir, -o: Output directory for files (default: output)

• --verbose, -v: Enable verbose logging

• --version: Show version information

Environment Variables

• MCP_HOST: Host for HTTP Streamable transport

• MCP_PORT: Port for HTTP Streamable transport

• OUTPUT_DIR: Directory for saving visualizations

Tool Examples

Validate SMILES

Get Molecular Information

Create RDKit Visualization

Create Network Visualization

Create Interactive Plotly Visualization

Compare All Visualizations

Batch Processing

Convert Content to ImageContent

Example Molecules

The server works with various types of molecules:

• Simple molecules: CCO (ethanol)

• Drug molecules: CC(C)CC1=CC=C(C=C1)C(C)C(=O)O (ibuprofen)

• Complex structures: CN1C=NC2=C1C(=O)N(C(=O)N2C)C (caffeine)

• Aromatic compounds: C1=CC=C(C=C1)C2=CC=CC=C2 (biphenyl)

Integration with MCP Clients

This server can be integrated with any MCP-compatible client such as:

• Claude Desktop

• VS Code with MCP extension

• Custom MCP clients

Client Configuration

Add the server to your MCP client configuration:

Output Formats

Images

• Format: PNG

• Encoding: Base64

• Usage: Can be embedded in HTML, displayed in applications, or saved to files

Interactive Visualizations

• Format: JSON (Plotly)

• Features: Zoom, pan, hover information, interactive elements

• Base64 Encoded: Returns as ImageContent with application/vnd.plotly.v1+json mimetype

• Plain Text: Returns as TextContent with raw Plotly figure data for programmatic use

Data

• Format: JSON

• Content: Molecular properties, validation results, error messages

Error Handling

The server includes comprehensive error handling:

• Invalid SMILES strings

• Missing dependencies

• Processing errors

• Network/graph generation issues

All errors are returned as structured JSON responses with descriptive messages.

Dependencies

Required

• mcp[cli] - MCP Python SDK

• rdkit-pypi - Molecular processing

• matplotlib - Custom visualizations

• networkx - Network graphs

• plotly - Interactive visualizations

• numpy - Numerical operations

• pandas - Data manipulation

• pillow - Image processing

• uvicorn - ASGI server

• fastapi - Web framework

Optional

• seaborn - Enhanced plotting (if available)

Development

Project Structure

Adding New Visualizations

To add new visualization types:

1. Add the tool decorator to the setup_tools method

2. Implement the visualization logic

3. Return results in the expected JSON format

4. Update the compare_visualizations method to include the new type

Testing

Test the server with example SMILES strings: