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

validate_smiles - Validate SMILES strings using RDKit
get_molecular_info - Get detailed molecular information and properties
visualize_rdkit - Create RDKit 2D molecular visualizations
visualize_network - Create network graph visualizations
visualize_plotly - Create interactive Plotly visualizations
visualize_custom_matplotlib - Create custom matplotlib visualizations
compare_visualizations - Generate all visualization types for comparison
batch_visualize - Process multiple SMILES strings

Debug/Development Tools

store_plotly_json - Store Plotly JSON visualizations for debugging/development
get_stored_plotly_json - Retrieve stored Plotly JSON with optional base64 encoding
list_stored_plotly_keys - List all stored Plotly JSON keys
clear_stored_plotly_data - Clear all stored Plotly JSON data
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

Clone or download the project
Install dependencies:

pip install -r requirements.txt

Or using uv (recommended):

uv pip install -r requirements.txt

Quick Start

Option 1: Direct Installation

Install dependencies
```
pip install -r requirements.txt
```

Run the server

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

Option 2: Using uv (Recommended)

Install dependencies with uv
```
uv pip install -r requirements.txt
```

Run the server

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

Option 3: Development Mode (Linux/macOS)

Make entrypoint script executable
```
chmod +x dev_entrypoint.sh
```
Run with development entrypoint
```
./dev_entrypoint.sh
```

Option 4: Docker

Build and run with Docker Compose
```
docker-compose up -d
```

Or build manually

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

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:

Add the tool decorator to the setup_tools method
Implement the visualization logic
Return results in the expected JSON format
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

SMILES Visualizer MCP Server

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

validate_smiles - Validate SMILES strings using RDKit
get_molecular_info - Get detailed molecular information and properties
visualize_rdkit - Create RDKit 2D molecular visualizations
visualize_network - Create network graph visualizations
visualize_plotly - Create interactive Plotly visualizations
visualize_custom_matplotlib - Create custom matplotlib visualizations
compare_visualizations - Generate all visualization types for comparison
batch_visualize - Process multiple SMILES strings

Debug/Development Tools

store_plotly_json - Store Plotly JSON visualizations for debugging/development
get_stored_plotly_json - Retrieve stored Plotly JSON with optional base64 encoding
list_stored_plotly_keys - List all stored Plotly JSON keys
clear_stored_plotly_data - Clear all stored Plotly JSON data
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

Clone or download the project
Install dependencies:

pip install -r requirements.txt

Or using uv (recommended):

uv pip install -r requirements.txt

Quick Start

Option 1: Direct Installation

Install dependencies
```
pip install -r requirements.txt
```

Run the server

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

Option 2: Using uv (Recommended)

Install dependencies with uv
```
uv pip install -r requirements.txt
```

Run the server

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

Option 3: Development Mode (Linux/macOS)

Make entrypoint script executable
```
chmod +x dev_entrypoint.sh
```
Run with development entrypoint
```
./dev_entrypoint.sh
```

Option 4: Docker

Build and run with Docker Compose
```
docker-compose up -d
```

Or build manually

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

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:

Add the tool decorator to the setup_tools method
Implement the visualization logic
Return results in the expected JSON format
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