Content
# ChemMCP - Chemical Molecular Computing Platform
ChemMCP is a collection of chemical molecular computing tools based on the Model Context Protocol (MCP), providing 19 specialized tools for chemical molecular processing.
## 🚀 Quick Start
### Environment Requirements
- Python 3.11+ (Recommended: Python 3.11 or 3.12)
- Conda environment manager
### Installation Steps
1. Create a conda environment:
```bash
conda create -n chemmcp python=3.11
conda activate chemmcp
```
2. Install dependencies:
```bash
pip install -r requirements.txt
```
3. Install ChemMCP:
```bash
pip install -e .
```
### Installation Options
ChemMCP offers flexible installation options, allowing you to choose based on your needs:
#### Option 1: Basic Installation (Recommended)
```bash
# Install core dependencies, supporting 17 tools
pip install -r requirements.txt
```
**Supported Tools**: All tools except `MoleculeCaptioner` and `MoleculeGenerator`
#### Option 2: Full Installation (Including AI Tools)
```bash
# Method A: Using optional dependency group
pip install -e ".[ai]"
# Method B: Manually install AI dependencies
pip install -r requirements.txt
pip install transformers>=4.20.0 torch>=1.9.0
```
**Supported Tools**: All 19 tools, including AI-driven molecular description and generation features
#### Option 3: Development Environment
```bash
# Install all dependencies and development tools
pip install -e ".[all,dev]"
```
### Configure Environment Variables
Set the corresponding API keys based on the tools you are using:
```bash
# Required for web search tools (mandatory)
export TAVILY_API_KEY="your_tavily_api_key"
# Required for LLM tools (mandatory)
export LLM_MODEL_NAME="openai/gpt-4o"
export OPENAI_API_KEY="your_openai_api_key"
# Required for ChemSpace tools (optional, used as a fallback only when PubChem lookup fails)
export CHEMSPACE_API_KEY="your_chemspace_api_key"
```
## 🔧 Tool List
### 1. WebSearch - Web Search
**Function**: Perform web searches to obtain chemistry-related information
**Input**: Search query string
**Output**: Search results and related links
### 2. MoleculeWeight - Molecular Weight Calculation
**Function**: Calculate the molecular weight of a molecule
**Input**: SMILES molecular structure string
**Output**: Molecular weight value
### 3. MoleculeAtomCount - Atom Count
**Function**: Count the number of various atoms in a molecule
**Input**: SMILES molecular structure string
**Output**: Count statistics of each atom type
### 4. MoleculeSimilarity - Molecular Similarity
**Function**: Calculate the Tanimoto similarity between two molecules
**Input**: Two SMILES molecular structure strings
**Output**: Similarity score (0-1)
### 5. FunctionalGroups - Functional Group Recognition
**Function**: Identify functional groups present in a molecule
**Input**: SMILES molecular structure string
**Output**: List of detected functional groups
### 6. SmilesCanonicalization - SMILES Canonicalization
**Function**: Convert SMILES strings to a canonical form
**Input**: SMILES molecular structure string
**Output**: Canonical SMILES string
### 7. Iupac2Smiles - IUPAC Name to SMILES
**Function**: Convert IUPAC chemical names to SMILES format
**Input**: IUPAC chemical name
**Output**: Corresponding SMILES string
### 8. Smiles2Iupac - SMILES to IUPAC Name
**Function**: Convert SMILES format to IUPAC chemical names
**Input**: SMILES molecular structure string
**Output**: Corresponding IUPAC chemical name
### 9. Smiles2Formula - SMILES to Molecular Formula
**Function**: Convert SMILES format to molecular formula
**Input**: SMILES molecular structure string
**Output**: Molecular formula (e.g., C2H6O)
### 10. Name2Smiles - Common Name to SMILES
**Function**: Convert common names of chemical substances to SMILES format
**Input**: Chemical substance name
**Output**: Corresponding SMILES string
### 11. Selfies2Smiles - SELFIES to SMILES
**Function**: Convert SELFIES format to SMILES format
**Input**: SELFIES string
**Output**: Corresponding SMILES string
### 12. Smiles2Selfies - SMILES to SELFIES
**Function**: Convert SMILES format to SELFIES format
**Input**: SMILES molecular structure string
**Output**: Corresponding SELFIES string
### 13. Smiles2Cas - SMILES to CAS Number
**Function**: Convert SMILES format to CAS registration number
**Input**: SMILES molecular structure string
**Output**: Corresponding CAS registration number
### 14. MoleculeSmilesCheck - SMILES Validation
**Function**: Validate the syntax correctness of SMILES strings
**Input**: SMILES molecular structure string
**Output**: Validation result (valid/invalid)
### 15. ReactionSmilesCheck - Reaction SMILES Validation
**Function**: Validate the syntax correctness of reaction SMILES strings
**Input**: Reaction SMILES string
**Output**: Validation result (valid/invalid)
### 16. MoleculeVisualizer - Molecular Visualization
**Function**: Generate 2D structure images of molecules
**Input**: SMILES molecular structure string
**Output**: Molecular structure image
### 17. MoleculeCaptioner - Molecular Description Generation
**Function**: Generate textual descriptions of molecules using AI
**Input**: SMILES molecular structure string
**Output**: Detailed textual description of the molecule
### 18. MoleculeGenerator - Molecular Generation
**Function**: Generate molecular structures based on descriptions using AI
**Input**: Molecular description text
**Output**: Corresponding SMILES molecular structure
### 19. MoleculeModifier - Molecular Modification
**Function**: Perform chemical modifications and derivatizations on molecules
**Input**: SMILES molecular structure string
**Output**: Options for modified molecular structures
## 📖 Usage Example
```bash
# Start the MCP server using specific tools
python -m chemmcp --tools WebSearch MoleculeWeight MoleculeAtomCount
# Or use all tools
python -m chemmcp --tools WebSearch MoleculeWeight MoleculeAtomCount MoleculeSimilarity FunctionalGroups SmilesCanonicalization Iupac2Smiles Smiles2Iupac Smiles2Formula Name2Smiles Selfies2Smiles Smiles2Selfies Smiles2Cas MoleculeSmilesCheck ReactionSmilesCheck MoleculeVisualizer MoleculeCaptioner MoleculeGenerator MoleculeModifier
```
## 🔧 MCP Configuration
Add the following configuration to your MCP client configuration file:
```json
{
"mcpServers": {
"ChemMCP": {
"command": "/opt/miniconda3/envs/chemmcp/bin/python", // How to find the path: conda activate chemmcp && which python
"args": [
"-m", "chemmcp",
"--tools",
"WebSearch",
"MoleculeWeight",
"MoleculeAtomCount",
"MoleculeSimilarity",
"FunctionalGroups",
"SmilesCanonicalization",
"Iupac2Smiles",
"Smiles2Iupac",
"Smiles2Formula",
"Name2Smiles",
"Selfies2Smiles",
"Smiles2Selfies",
"Smiles2Cas",
"MoleculeSmilesCheck",
"ReactionSmilesCheck",
"MoleculeVisualizer",
"MoleculeCaptioner",
"MoleculeGenerator",
"MoleculeModifier"
],
"toolCallTimeoutMillis": 300000,
"env": {
"TAVILY_API_KEY": "your_tavily_api_key_here",
"LLM_MODEL_NAME": "openai/gpt-4o",
"OPENAI_API_KEY": "your_openai_api_key_here",
"CHEMSPACE_API_KEY": "your_chemspace_api_key_here", // Optional: used only when additional database lookup is needed
"PATH": "/opt/miniconda3/envs/chemmcp/bin:/usr/local/bin:/usr/bin:/bin" // How to find the path: conda activate chemmcp && echo $PATH
}
}
}
}
```
**Note**:
- **How to find the correct Python path**:
```bash
# Activate your conda environment
conda activate chemmcp
# Check Python path
which python
# Copy the output path and replace it in the above configuration
```
- Please replace the API keys with your actual keys.
- **CHEMSPACE_API_KEY is optional**: It will only be used by the `Iupac2Smiles` tool when PubChem lookup fails and ChemSpace is used as a fallback database.
- Ensure your Python environment version is 3.11 or higher.
## 🛠️ Dependencies
- **RDKit**: Core library for molecular processing and computation
- **PubChemPy**: Interface for the PubChem database
- **SELFIES**: Self-referential embedded string representation of molecules
- **rdchiral**: Chirality handling for molecules
- **synspace**: Molecular space exploration and modification
- **tavily-python**: Web search API
- **litellm**: Unified LLM API interface
- **requests**: HTTP request library
## 📄 License
This project is licensed under the MIT License. See the LICENSE file for details.
---
**Note**: Some tools require corresponding API keys. Please ensure that environment variables are correctly set before use.
