pubchem-mcp-server — Claude Code MCP server: PubChem chemistry
Pulls PubChem data into your coding agent: compound search, properties, hazard data, bioactivity and 3D structures, all as tool calls.
claude mcp add --transport http pubchem-mcp-server https://pubchem.caseyjhand.com/mcpWhat pubchem-mcp-server does
This MCP server puts PubChem behind ten tools. pubchem_search_compounds takes a name, SMILES, InChI, InChIKey, Hill formula, substructure, superstructure or a 2D similarity query. From a CID the agent can then grab physicochemical properties and classification, a PNG diagram, 3D conformer coordinates as parsed JSON or raw SDF, cross-references to PubMed, patents, genes and CAS/EC numbers, GHS hazard data for a batch of compounds, and full bioactivity profiles with targets and activity values. Assays are searchable by biological target, and a summary tool covers assays, genes, proteins and taxonomy.
Six URI resources mirror much of this (pubchem://compound/{cid}/safety and so on), but plenty of MCP clients ignore resources entirely. If yours does, the tools carry everything. Caps are worth knowing up front: search returns at most 200 CIDs per page, details accept 100 CIDs, descriptions and classification only cover the first 10 CIDs, and paging through formula or structure searches stops at 10 000 with an offset_ceiling_exceeded error.
You can use the hosted endpoint at https://pubchem.caseyjhand.com/mcp or run it yourself with npx -y @cyanheads/pubchem-mcp-server, which needs Node.js. The install commands with MCP_TRANSPORT_TYPE, MCP_SESSION_MODE and MCP_HTTP_PORT carry placeholders. Fill them in before running, otherwise the literal <...> values land in your config and the stdio server won't come up.
What it helps with
- find a compound from a SMILES string or InChIKey
- pull every CID matching a molecular formula in Hill notation
- check GHS hazard classes across several compounds at once
- get atom coordinates and bonds for a 3D conformer
- locate bioassays tied to a gene or UniProt accession
Example prompts for the agent
- Search PubChem for compounds with formula C9H8O4 and list their CIDs
- Fetch GHS safety data and synonyms for CID 2244
- Which PubChem assays target the EGFR gene?
How to install pubchem-mcp-server
1Platform CLI: remote server
claude mcp add --transport http pubchem-mcp-server https://pubchem.caseyjhand.com/mcp2Platform CLI
claude mcp add --env MCP_LOG_LEVEL=<MCP_LOG_LEVEL> --env MCP_TRANSPORT_TYPE=<MCP_TRANSPORT_TYPE> --env MCP_SESSION_MODE=<MCP_SESSION_MODE> --env MCP_HTTP_HOST=<MCP_HTTP_HOST> --env MCP_HTTP_PORT=<MCP_HTTP_PORT> --transport stdio pubchem-mcp-server -- npx -y @cyanheads/pubchem-mcp-serverReplace <…> with your own values. 2 more environment variables are in the server README
1Platform CLI: remote server
codex mcp add pubchem-mcp-server --url https://pubchem.caseyjhand.com/mcp2Platform CLI
codex mcp add pubchem-mcp-server --env MCP_LOG_LEVEL=<MCP_LOG_LEVEL> --env MCP_TRANSPORT_TYPE=<MCP_TRANSPORT_TYPE> --env MCP_SESSION_MODE=<MCP_SESSION_MODE> --env MCP_HTTP_HOST=<MCP_HTTP_HOST> --env MCP_HTTP_PORT=<MCP_HTTP_PORT> -- npx -y @cyanheads/pubchem-mcp-serverReplace <…> with your own values. 2 more environment variables are in the server README
Config file
{
"mcpServers": {
"pubchem-mcp-server": {
"url": "https://pubchem.caseyjhand.com/mcp"
}
}
}{
"mcpServers": {
"pubchem-mcp-server": {
"command": "npx",
"args": [
"-y",
"@cyanheads/pubchem-mcp-server"
],
"env": {
"MCP_LOG_LEVEL": "<MCP_LOG_LEVEL>",
"MCP_TRANSPORT_TYPE": "<MCP_TRANSPORT_TYPE>",
"MCP_SESSION_MODE": "<MCP_SESSION_MODE>",
"MCP_HTTP_HOST": "<MCP_HTTP_HOST>",
"MCP_HTTP_PORT": "<MCP_HTTP_PORT>"
}
}
}
}Replace <…> with your own values. 2 more environment variables are in the server README
Config file
{
"servers": {
"pubchem-mcp-server": {
"type": "http",
"url": "https://pubchem.caseyjhand.com/mcp"
}
}
}{
"servers": {
"pubchem-mcp-server": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@cyanheads/pubchem-mcp-server"
],
"env": {
"MCP_LOG_LEVEL": "<MCP_LOG_LEVEL>",
"MCP_TRANSPORT_TYPE": "<MCP_TRANSPORT_TYPE>",
"MCP_SESSION_MODE": "<MCP_SESSION_MODE>",
"MCP_HTTP_HOST": "<MCP_HTTP_HOST>",
"MCP_HTTP_PORT": "<MCP_HTTP_PORT>"
}
}
}
}Replace <…> with your own values. 2 more environment variables are in the server README
1Platform CLI: remote server
gemini mcp add -t http pubchem-mcp-server https://pubchem.caseyjhand.com/mcp2Platform CLI
gemini mcp add -e MCP_LOG_LEVEL=<MCP_LOG_LEVEL> -e MCP_TRANSPORT_TYPE=<MCP_TRANSPORT_TYPE> -e MCP_SESSION_MODE=<MCP_SESSION_MODE> -e MCP_HTTP_HOST=<MCP_HTTP_HOST> -e MCP_HTTP_PORT=<MCP_HTTP_PORT> pubchem-mcp-server npx -y @cyanheads/pubchem-mcp-serverReplace <…> with your own values. 2 more environment variables are in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about pubchem-mcp-server
How do I install pubchem-mcp-server in Claude Code?
For the hosted server run claude mcp add --transport http pubchem-mcp-server https://pubchem.caseyjhand.com/mcp. For a local one run `claude mcp add --env MCP_LOG_LEVEL=<MCP_LOG_LEVEL> --env MCP_TRANSPORT_TYPE=<MCP_TRANSPORT_TYPE> --env MCP_SESSION_MODE=<MCP_SESSION_MODE> --env MCP_HTTP_HOST=<MCP_HTTP_HOST> --env MCP_HTTP_PORT=<MCP_HTTP_PORT> --transport stdio pubchem-mcp-server -- npx -y @cyanheads/pubchem-mcp-server`.
What does pubchem-mcp-server do?
It lets an agent query PubChem: look up compounds by identifier, formula or structure, read properties and structure images by CID, and retrieve safety records, bioactivity, cross-references and 3D conformers.
Why does deep paging in a formula or structure search fail?
Those two search types cap offset at 10 000 and return offset_ceiling_exceeded past that. Identifier and assay searches page all the way to the end of their matches.
