ChemMCP is a chemistry toolkit that empowers AI assistants with advanced chemistry capabilities.

This guide will help you quickly set up and start using ChemMCP.

Quick Setup

1. Install uv

   We recommend using <a href=https://github.com/astral-sh/uv target=_blank>uv, a fast Python package and project manager. Install uv with the following commands:

   # On macOS and Linux
   curl -LsSf https://astral.sh/uv/install.sh | sh
   

   # On Windows, use Powershell
   powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
   

2. Download ChemMCP

   git clone https://github.com/OSU-NLP-Group/ChemMCP.git
   

3. Set Up and Install

   cd ChemMCP
   uv sync
   

   This above commands create a Python virtual environment in the .venv folder with all required packages installed. Then activate the environment:

   # On macOS and Linux
   source .venv/bin/activate
   

   # On Windows (CMD)
   .venv\Scripts\activate.bat
   

   To install ChemMCP:

   uv pip install -e . --no-build-isolation
   

   Optional: Use an Existing Environment

   To install ChemMCP in an existing Python or Conda environment:

   # Install dependencies
   pip install -r requirements
   
   # Install ChemMCP
   pip install -e --no-build-isolation
   

4. Install docker

   If you are to use the <a href=https://osu-nlp-group.github.io/ChemMCP/tools/python_executor/>PythonExecutor tool, which relies on docker, please follow <a href=https://osu-nlp-group.github.io/ChemMCP/tools/python_executor/>its official doc to install it. Otherwise, please exclude it from the tools to run, using <a href=https://osu-nlp-group.github.io/ChemMCP/quick-config>QuickConfig, or the MCP server would not successfully start.

Usage

ChemMCP supports two usage modes:

• MCP: Run ChemMCP as a <a href=https://claude.ai/download target=_blank>Model Context Protocol (MCP) server to easily integrate with MCP-compatible clients like <a href=https://github.com/punkpeye/awesome-mcp-clients target=_blank>Claude Desktop and <a href=https://github.com/punkpeye/awesome-mcp-clients target=_blank>more.

• Python Calling: Use ChemMCP as a standard Python package directly in your Python code.

The following sections will walk you through the basic usage of both modes, after setting up required API keys.

Required API Keys

Set the following environment variables to enable tool functionality:

• CHEMSPACE_API_KEY: Get from <a href=https://chem-space.com/ target=_blank>ChemSpace

• RXN4CHEM_API_KEY: Get from <a href=https://rxn.res.ibm.com target=_blank>IBM RXN4Chem

• TAVILY_API_KEY: Get from <a href=https://tavily.com/ target=_blank>Tavily

• LLM_MODEL_NAME: Your preferred LLM model name (e.g., openai/gpt-4o) in <a href=https://docs.litellm.ai/docs/#basic-usage target=_blank>LiteLLM format

• Other LLM credentials, such as OPENAI_API_KEY, or Azure-specific keys if using Azure OpenAI, detailed at <a href=https://docs.litellm.ai/docs/#basic-usage target=_blank>LiteLLM usage

MCP Mode

You can run ChemMCP as an MCP server to integrate with different clients. Here we show two examples, and the configuration should be very similar for other senarios.

Claude Desktop Integration

Follow <a href=https://modelcontextprotocol.io/quickstart/server#testing-your-server-with-claude-for-desktop target=_blank>this guide to set up the configuration file of Claude Desktop. The JSON config for ChemMCP:

{
    "mcpServers": {
        "ChemMCP": {
            "command": "/ABSTRACT/PATH/TO/uv",  // Use which uv to get its path
            "args": ["run", "-m", "chemmcp"],
            "toolCallTimeoutMillis": 300000,  // Set this value because some tools may be slow in response of requests
            "env": {
                "CHEMSPACE_API_KEY": "API_KEY",
                "RXN4CHEM_API_KEY": "API_KEY",
                "TAVILY_API_KEY": "API_KEY",
                "LLM_MODEL_NAME": "openai/gpt-4o",  // Or any other LLM names supported by LiteLLM
                // Add required LLM credentials
                // ...
            }
        }
    }
}

Integration with LLM APIs (e.g., OpenAI Agents SDK)

LLM providers provide their SDKs to support MCP servers. Take <a href=https://openai.github.io/openai-agents-python/mcp/ target=_blank>OpenAI Agents SDK as an example, connect to ChemMCP with the following code:

async with MCPServerStdio(
    params={
        "command": "/ABSTRACT/PATH/TO/uv",  # Use which uv to get its path
        "args": ["--directory", "/ABSTRACT/PATH/TO/ChemMCP", "run", "-m", "chemmcp"],
        "toolCallTimeoutMillis": 300000,  # Set this value because some tools may be slow in response of requests
        "env": {
        		"CHEMSPACE_API_KEY": "API_KEY",
            "RXN4CHEM_API_KEY": "API_KEY",
            "TAVILY_API_KEY": "API_KEY",
            "LLM_MODEL_NAME": "openai/gpt-4o-2024-08-06",  # Or any other LLM names supported by LiteLLM
          	# Aad required LLM credentials
          	# ...
        }
    }
) as server:
    tools = await server.list_tools()

Python Calling Mode

ChemMCP tools can also be called directly in Python:

import os
from chemmcp.tools import WebSearch  # or any of the tool names

# Of course, you can set only those variables required by the tools to use
envs = {
    "CHEMSPACE_API_KEY": "API_KEY",
    "RXN4CHEM_API_KEY": "API_KEY",
    "TAVILY_API_KEY": "API_KEY",
    "LLM_MODEL_NAME": "openai/gpt-4o-2024-08-06",  # Or any other LLM names supported by LiteLLM
    # Aad required LLM credentials
    # ...
}

for key, value in envs:
  os.environ[key] = value

web_search = WebSearch()
result = web_search.run_code('What is the boiling point of water?')

Available Tools

Currently, ChemMCP tools fall into three categories:

1. General Tools: General and broad information retrieval and web searching.

2. Molecule Tools: Various analyses, predictions, and conversions related to chemical compounds and their properties.

3. Reaction Tools: Chemical reaction prediction and analysis.

See the full list and documentation on the <a href=https://osu-nlp-group.github.io/ChemMCP/tools>Tools page.

Next Steps

• Browse all tools on the <a href=https://osu-nlp-group.github.io/ChemMCP/tools>Tools page.
• Use <a href=https://osu-nlp-group.github.io/ChemMCP/quick-config>QuickConfig to auto-configure tools based on your needs.
• Contribute your own tools or improve existing ones (see <a href=https://osu-nlp-group.github.io/ChemMCP/dev-guide>Dev Guide).

Contact

Have questions or feedback?

• Open an issue for bug reports or feature requests on our <a href=https://github.com/OSU-NLP-Group/ChemMCP target=_blank>GitHub repository.

• Email us at yu.3737 at osu.edu – we are eager to know your ideas and suggestions!