Chemspace

You can use the chemspace MCP Server to query the Chemspace API for exact, substructure, and similarity searches across in-stock and make-on-demand compounds, with support for multiple product categories and shipping country targeting.

How to use

You interact with the MCP server by running it locally and then making search requests through your MCP client. The server exposes tools to perform exact SMILES searches, substructure searches, and similarity searches. You can specify product categories to search across in-stock and make-on-demand inventories and set a destination shipping country using its two-letter ISO code.

Typical workflows you can perform include: performing an exact match for a SMILES string, finding compounds that contain a specific substructure, and identifying structurally similar compounds. For each search you can control pagination with page and count, and you can choose which product categories to search (CSSB, CSSS, CSMB, CSMS, CSCS). Ensure you provide your API key so the server can access the Chemspace API.

How to install

Prerequisites you need before installing:

• Python 3.13 or newer
• The Chemspace API key for authenticating requests
• The uv runtime to run the MCP server locally

Install the uv runtime on your operating system:

brew install uv
# Linux/WSL2
curl -LsSf https://astral.sh/uv/install.sh | sh```

Setup steps to run the MCP server locally:
```# Step 1: Set your Chemspace API key
export CHEMSPACE_API_KEY="your-api-key-here"
# Step 2: Start the MCP server
uv run chemspace-mcp```

## Configuration and security

Set your API key as an environment variable so the MCP server can authenticate with Chemspace. You can also configure the API key through environment configuration files if you manage secrets that way.

Security note: keep your API key confidential and avoid exposing it in logs or publicly accessible files. Use a secure secret management approach for production deployments.

## Usage details and parameters

The server supports these search modes with the following parameters:
- smiles (string): The SMILES string to search for
- shipToCountry (string): ISO country code for shipping (default: US)
- count (integer): Maximum results per page (default: 10)
- page (integer): Page number for pagination (default: 1)
- categories (list): Product categories to search, including:
- CSSB: In-stock building blocks
- CSSS: In-stock screening compounds
- CSMB: Make-on-demand building blocks
- CSMS: Make-on-demand screening compounds
- CSCS: Custom requests
Each search type (exact, substructure, similarity) uses the same parameter set, with the query parameter defining the search shape.

## Project structure and environment

The MCP server implements the search tools and token management in the following components:
- src/chemspace\_mcp/
- \_\_init\_\_.py: Entry point and MCP server initialization
- tools.py: Tool definitions for chemical searches
- tokenmanager.py: Token management for API authentication
- example/: Example integration and secrets configuration (not in version control)
- pyproject.toml: Project metadata and dependencies

## Troubleshooting and tips

If you encounter authentication errors, verify that CHEMSPACE\_API\_KEY is correctly set in your environment and accessible to the MCP server process. If the server fails to start, check that your Python runtime meets the required version (3.13+) and that the uv runtime is installed correctly. Ensure network access to Chemspace API endpoints is available from your running environment.

## Notes

This MCP server provides a dedicated wrapper around the Chemspace API to enable agents to search for building blocks and screening compounds using exact, substructure, and similarity searches across multiple product categories with control over shipping regions.

## Available tools

### search\_exact

Find exact molecular matches by a SMILES string. Accepts parameters smiles, shipToCountry, count, page, and categories.

### search\_substructure

Find compounds that contain a given substructure. Uses the same parameter set as search\_exact.

### search\_similarity

Find compounds structurally similar to a given SMILES string. Uses the same parameter set as search\_exact.