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:

pip install -r requirements.txt

Or using uv (recommended):

uv pip install -r requirements.txt

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:

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

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

# Validate a SMILES string
result = await validate_smiles("CCO")
# Returns: {"valid": true, "message": "Valid SMILES", "canonical_smiles": "CCO"}

Get Molecular Information

# Get detailed molecular information
info = await get_molecular_info("CCO")
# Returns molecular weight, atom count, properties, etc.

Create RDKit Visualization

# Create RDKit 2D visualization
result = await visualize_rdkit("CCO", size="400,300")
# Returns base64 encoded PNG image

Create Network Visualization

# Create network graph
result = await visualize_network("CCO", layout="spring")
# Returns base64 encoded PNG image with network layout

Create Interactive Plotly Visualization

# Create interactive visualization (base64 encoded JSON)
result = await visualize_plotly("CCO")
# Returns base64 encoded JSON data as ImageContent

# Create interactive visualization (plain text JSON)
result = await visualize_plotly("CCO", encode_base64=False)
# Returns plain text JSON data as TextContent

Compare All Visualizations

# Generate all visualization types (base64 encoded Plotly JSON)
results = await compare_visualizations("CCO")
# Returns all visualization types and molecular info

# Generate all visualization types (plain text Plotly JSON)
results = await compare_visualizations("CCO", encode_base64=False)
# Returns all visualization types with plain text JSON for Plotly

Batch Processing

# Process multiple molecules
smiles_list = ["CCO", "CC(C)CC1=CC=C(C=C1)C(C)C(=O)O", "CN1C=NC2=C1C(=O)N(C(=O)N2C)C"]
results = await batch_visualize(smiles_list, visualization_type="rdkit")
# Returns visualizations for all molecules

# Process multiple molecules with Plotly (plain text JSON)
results = await batch_visualize(smiles_list, visualization_type="plotly", encode_base64=False)
# Returns Plotly visualizations in plain text JSON format for all molecules

Convert Content to ImageContent

# Convert SMILES string to ImageContent (base64 encoded)
result = await convert_to_image("CCO", mime_type="smiles_seq")
# Returns ImageContent with base64 encoded SMILES data

# Convert JSON data to ImageContent (plain text)
json_data = '{"molecule": "CCO", "weight": 46.07}'
result = await convert_to_image(json_data, mime_type="application/json", encode_base64=False)
# Returns ImageContent with plain text JSON data

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:

{
  "mcpServers": {
    "smiles-visualizer": {
      "command": "python",
      "args": ["path/to/smiles_visualizer_mcp/server.py", "--host", "127.0.0.1", "--port", "8080"],
      "env": {
        "MCP_HOST": "127.0.0.1",
        "MCP_PORT": "8080"
      }
    }
  }
}

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

smiles_visualizer_mcp/
├── server.py          # Main MCP server implementation
├── requirements.txt   # Python dependencies
└── README.md         # This file

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:

# Start the server
python server.py

# Test with curl (in another terminal)
curl -X POST http://127.0.0.1:8080/tools/validate_smiles/call \
  -H "Content-Type: application/json" \
  -d '{"arguments": {"smiles": "CCO"}}'

## License

This project is open source and available under the MIT License.

## Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues for bugs and feature requests.

## Support

For issues and questions:
1. Check the error messages in the server logs
2. Verify all dependencies are installed correctly
3. Ensure SMILES strings are valid
4. Check that the required libraries (RDKit, matplotlib, etc.) are available

## Related Projects

- [RDKit](https://www.rdkit.org/) - Open-source cheminformatics toolkit
- [Model Context Protocol](https://modelcontextprotocol.io/) - Protocol for AI context
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) - Official Python implementation