Content
# PubChem MCP Server
[](https://smithery.ai/server/@JackKuo666/pubchem-mcp-server)
🧪 Enable AI assistants to search and access chemical compound information through a simple MCP interface.
The PubChem MCP Server provides a bridge between AI assistants and PubChem's chemical database through the Model Context Protocol (MCP). It allows AI models to search for chemical compounds and access their detailed information in a programmatic way.
🤝 Contribute • 📝 Report Bug
## ✨ Core Features
- 🔎 Compound Search: Query PubChem compounds by name, SMILES, or CID ✅
- 🧪 Chemical Structure: Access molecular structures and identifiers ✅
- 📊 Property Data: Retrieve detailed chemical and physical properties ✅
- 🔬 Advanced Search: Combine multiple parameters for precise queries ✅
- 🧬 Molecular Visualization: Generate and display molecular structures 📝
- 📈 Property Analysis: Compare properties across multiple compounds 📝
- 🗃️ Local Storage: Save frequently used compounds for faster access 📝
- 📝 Chemistry Prompts: Specialized prompts for chemical analysis 📝
## 🚀 Quick Start
### Installing via Smithery
To install PubChem Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@JackKuo666/pubchem-mcp-server):
#### Claude
```bash
npx -y @smithery/cli@latest install @JackKuo666/pubchem-mcp-server --client claude --config "{}"
```
#### Cursor
Paste the following into Settings → Cursor Settings → MCP → Add new server:
- Mac/Linux
```s
npx -y @smithery/cli@latest run @JackKuo666/pubchem-mcp-server --client cursor --config "{}"
```
#### Windsurf
```sh
npx -y @smithery/cli@latest install @JackKuo666/pubchem-mcp-server --client windsurf --config "{}"
```
### CLine
```sh
npx -y @smithery/cli@latest install @JackKuo666/pubchem-mcp-server --client cline --config "{}"
```
### Installing Manually
Install using uv:
```bash
uv tool install pubchem-mcp-server
```
For development:
```bash
# Clone and set up development environment
git clone https://github.com/JackKuo666/PubChem-MCP-Server.git
cd PubChem-MCP-Server
# Create and activate virtual environment
uv venv
source .venv/bin/activate
uv pip install -r requirements.txt
```
## 📊 Usage
Start the MCP server:
```bash
python pubchem_server.py
```
Once the server is running, you can use the provided MCP tools in your AI assistant or application. Here are some examples of how to use the tools:
### Example 1: Search for compounds by name
```python
result = await mcp.use_tool("search_pubchem_by_name", {
"name": "aspirin",
"max_results": 3
})
print(result)
```
### Example 2: Search for compounds by SMILES notation
```python
result = await mcp.use_tool("search_pubchem_by_smiles", {
"smiles": "CC(=O)OC1=CC=CC=C1C(=O)O", # Aspirin's SMILES
"max_results": 2
})
print(result)
```
### Example 3: Get detailed information for a specific compound
```python
result = await mcp.use_tool("get_pubchem_compound_by_cid", {
"cid": 2244 # Aspirin's CID
})
print(result)
```
### Example 4: Perform an advanced search with multiple parameters
```python
result = await mcp.use_tool("search_pubchem_advanced", {
"name": "caffeine",
"formula": "C8H10N4O2",
"max_results": 2
})
print(result)
```
These examples demonstrate how to use the four main tools provided by the PubChem MCP Server. Adjust the parameters as needed for your specific use case.
## 🛠 MCP Tools
The PubChem MCP Server provides the following tools:
### search_pubchem_by_name
Search for chemical compounds on PubChem using a compound name.
**Parameters:**
- `name` (str): Name of the chemical compound
- `max_results` (int, optional): Maximum number of results to return (default: 5)
**Returns:** List of dictionaries containing compound information
### search_pubchem_by_smiles
Search for chemical compounds on PubChem using a SMILES string.
**Parameters:**
- `smiles` (str): SMILES notation of the chemical compound
- `max_results` (int, optional): Maximum number of results to return (default: 5)
**Returns:** List of dictionaries containing compound information
### get_pubchem_compound_by_cid
Fetch detailed information about a chemical compound using its PubChem CID.
**Parameters:**
- `cid` (int): PubChem Compound ID (CID)
**Returns:** Dictionary containing compound information
### search_pubchem_advanced
Perform an advanced search for compounds on PubChem.
**Parameters:**
- `name` (str, optional): Name of the chemical compound
- `smiles` (str, optional): SMILES notation of the chemical compound
- `formula` (str, optional): Molecular formula
- `cid` (int, optional): PubChem Compound ID
- `max_results` (int, optional): Maximum number of results to return (default: 5)
**Returns:** List of dictionaries containing compound information
## Usage with Claude Desktop
Add this configuration to your `claude_desktop_config.json`:
(Mac OS)
```json
{
"mcpServers": {
"pubchem": {
"command": "python",
"args": ["-m", "pubchem-mcp-server"]
}
}
}
```
(Windows version):
```json
{
"mcpServers": {
"pubchem": {
"command": "C:\\Users\\YOUR_USERNAME\\AppData\\Local\\Programs\\Python\\Python311\\python.exe",
"args": [
"-m",
"pubchem-mcp-server"
]
}
}
}
```
Using with Cline
```json
{
"mcpServers": {
"pubchem": {
"command": "bash",
"args": [
"-c",
"source /home/YOUR/PATH/mcp-hub/PubChem-MCP-Server/.venv/bin/activate && python /home/YOUR/PATH/mcp-hub/PubChem-MCP-Server/pubchem_server.py"
],
"env": {},
"disabled": false,
"autoApprove": []
}
}
}
```
After restarting Claude Desktop, the following capabilities will be available:
### Searching Compounds
You can ask Claude to search for chemical compounds using queries like:
```
Can you search PubChem for information about aspirin?
```
The search will return basic information about matching compounds including:
• Compound name
• CID (PubChem Compound ID)
• Molecular formula
• Molecular weight
### Getting Compound Details
Once you have a CID, you can ask for more details:
```
Can you show me the details for compound with CID 2244?
```
This will return:
• IUPAC name
• Molecular formula
• Molecular weight
• SMILES notation
• InChI and InChIKey
• Physical and chemical properties
• Synonyms
## 📝 TODO
### visualize_compound
Generate and display a 2D or 3D visualization of a chemical compound.
### compare_compounds
Compare properties and structures of multiple compounds.
### save_compound
Save a compound locally for faster access.
### list_saved_compounds
List all saved compounds.
### 📝 Chemistry Prompts
The server will offer specialized prompts to help analyze chemical compounds:
#### Compound Analysis Prompt
A comprehensive workflow for analyzing chemical compounds that only requires a compound ID:
```python
result = await call_prompt("deep-compound-analysis", {
"compound_id": "2244"
})
```
This prompt will include:
- Detailed instructions for using available tools
- A systematic workflow for compound analysis
- Comprehensive analysis structure covering:
- Chemical structure and properties
- Pharmacological properties
- Biological activities
- Applications and uses
- Safety and toxicity information
- Related compounds
## 📁 Project Structure
- `pubchem_server.py`: The main MCP server implementation using FastMCP
- `pubchem_search.py`: Contains example code for searching PubChem
## 🔧 Dependencies
- Python 3.10+
- FastMCP
- asyncio
- logging
- pubchempy (for PubChem API access)
- pandas (for data handling)
You can install the required dependencies using:
```bash
pip install mcp pubchempy pandas
```
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## 📄 License
This project is licensed under the MIT License.
## ⚠️ Disclaimer
This tool is for research purposes only. Please respect PubChem's terms of service and use this tool responsibly.
