pubchem-mcp-server

Get Compound 3D Structure

pubchem_get_compound_3d_structure

Read-onlyIdempotent

Retrieve a compound's default 3D conformer with atomic coordinates and bonds from PubChem by CID. Output as parsed JSON or raw SDF for docking, rendering, or conformer analysis.

Instructions

Get a compound's default 3D conformer — atomic coordinates and bonds — for one CID. format="json" (default) returns atoms and bonds parsed into structured fields; format="sdf" returns the raw V2000 SDF text for passthrough to docking, rendering, or conformer tools. Optionally lists alternate conformer IDs. Not every compound has computed 3D coordinates (large molecules, mixtures, and some salts do not).

Input Schema

TableJSON Schema

Name	Required	Description	Default
`cid`	Yes	PubChem Compound ID. Resolve from name/SMILES with pubchem_search_compounds.
`format`	No	Output format. "json" (default) returns parsed atoms and bonds. "sdf" returns the raw V2000 SDF text for passthrough to other tools.	json
`maxAtoms`	No	Cap the atoms returned in the format="json" preview. atomCount always reports the full total; omitted rows are disclosed via the truncated/shownAtoms enrichment. Defaults to the first 200 atoms.
`maxBonds`	No	Cap the bonds returned in the format="json" preview. bondCount always reports the full total; omitted rows are disclosed via the truncated/shownBonds enrichment. Defaults to the first 200 bonds.
`includeRawSdf`	No	For format="sdf", return the complete raw V2000 SDF even when it exceeds the safe line cap. Default false: an SDF longer than 500 lines is line-capped with disclosure. No effect when format="json".
`includeAlternateConformerIds`	No	List the IDs of additional computed conformers beyond the default. Slower than the default response. Default: false.

Output Schema

TableJSON Schema

Name	Required	Description
`cid`	No	PubChem Compound ID.
`sdf`	No	Raw V2000 SDF text. Populated when format="sdf".
`atoms`	No	Parsed atoms. Populated when format="json".
`bonds`	No	Parsed bonds. Populated when format="json".
`error`	No	Present when the call failed. Absent on success.
`notice`	No	Guidance naming which lists were capped and how to widen them.
`atomCap`	No	The atom cap applied (explicit maxAtoms or the safe default), when the atom list was capped.
`bondCap`	No	The bond cap applied (explicit maxBonds or the safe default), when the bond list was capped.
`atomCount`	No	Number of atoms in the conformer.
`bondCount`	No	Number of bonds in the conformer.
`truncated`	No	True when the atom list, bond list, or raw SDF was capped below its total. atomCount/bondCount always report the full totals.
`shownAtoms`	No	Atoms returned after the cap, when fewer than atomCount. Raise maxAtoms for more.
`shownBonds`	No	Bonds returned after the cap, when fewer than bondCount. Raise maxBonds for more.
`conformerId`	No	Default (primary) conformer ID. Present when includeAlternateConformerIds is set.
`shownSdfLines`	No	SDF lines returned when format="sdf" and the raw text was line-capped. Set includeRawSdf for the full record.
`alternateConformerIds`	No	Conformer IDs beyond the default. Present when includeAlternateConformerIds is set and alternates exist.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.7.0Oct 16, 2026

changedInput schema / properties / cid / maximum

Previous value: -9007199254740991New value: +2147483647

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_3d_structure`: PubChem has no computed 3D conformer for the requested CID. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_3d_structure`: PubChem returned 404 for the CID's 3D record, its answer both when the compound has no computed 3D conformer (common for very large molecules, mixtures, and undefined salts) and when no compound has the CID. Other values are possible when a failure originates below the handler."

Changed6 schema fields changedv0.6.5Sep 25, 2026
- removedInput schema / properties / cid / exclusiveMinimum
```
Removed value: -0
```
- addedInput schema / properties / cid / minimum
```
Added value: +1
```
- removedInput schema / properties / maxAtoms / exclusiveMinimum
```
Removed value: -0
```
- addedInput schema / properties / maxAtoms / minimum
```
Added value: +1
```
- removedInput schema / properties / maxBonds / exclusiveMinimum
```
Removed value: -0
```
- addedInput schema / properties / maxBonds / minimum
```
Added value: +1
```

Changed1 schema field changedv0.6.3Sep 20, 2026

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_3d_structure`: PubChem has no computed 3D conformer for the requested CID Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_3d_structure`: PubChem has no computed 3D conformer for the requested CID. Other values are possible when a failure originates below the handler."

Changed6 schema fields changedv0.6.1Aug 28, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "cid",
+      "atomCount",
+      "bondCount"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `no_3d_structure`: PubChem has no computed 3D conformer for the requested CID Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "no_3d_structure"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

removedOutput schema / required

Removed value: -[
-  "cid",
-  "atomCount",
-  "bondCount"
-]

Changed1 schema field changedv0.6.0Jul 30, 2026

changedInput schema / properties / includeAlternateConformerIds / description

Previous value: -"List the IDs of additional computed conformers beyond the default. Adds one extra API call. Default: false."New value: +"List the IDs of additional computed conformers beyond the default. Slower than the default response. Default: false."

Changed10 schema fields changedv0.2.5Jul 6, 2026

addedInput schema / properties / includeRawSdf

Added value: +{
+  "default": false,
+  "description": "For format=\"sdf\", return the complete raw V2000 SDF even when it exceeds the safe line cap. Default false: an SDF longer than 500 lines is line-capped with disclosure. No effect when format=\"json\".",
+  "type": "boolean"
+}

addedInput schema / properties / maxAtoms

Added value: +{
+  "description": "Cap the atoms returned in the format=\"json\" preview. atomCount always reports the full total; omitted rows are disclosed via the truncated/shownAtoms enrichment. Defaults to the first 200 atoms.",
+  "exclusiveMinimum": 0,
+  "maximum": 9007199254740991,
+  "type": "integer"
+}

addedInput schema / properties / maxBonds

Added value: +{
+  "description": "Cap the bonds returned in the format=\"json\" preview. bondCount always reports the full total; omitted rows are disclosed via the truncated/shownBonds enrichment. Defaults to the first 200 bonds.",
+  "exclusiveMinimum": 0,
+  "maximum": 9007199254740991,
+  "type": "integer"
+}

addedOutput schema / properties / atomCap

Added value: +{
+  "description": "The atom cap applied (explicit maxAtoms or the safe default), when the atom list was capped.",
+  "type": "number"
+}

addedOutput schema / properties / bondCap

Added value: +{
+  "description": "The bond cap applied (explicit maxBonds or the safe default), when the bond list was capped.",
+  "type": "number"
+}

addedOutput schema / properties / notice

Added value: +{
+  "description": "Guidance naming which lists were capped and how to widen them.",
+  "type": "string"
+}

addedOutput schema / properties / shownAtoms

Added value: +{
+  "description": "Atoms returned after the cap, when fewer than atomCount. Raise maxAtoms for more.",
+  "type": "number"
+}

addedOutput schema / properties / shownBonds

Added value: +{
+  "description": "Bonds returned after the cap, when fewer than bondCount. Raise maxBonds for more.",
+  "type": "number"
+}

addedOutput schema / properties / shownSdfLines

Added value: +{
+  "description": "SDF lines returned when format=\"sdf\" and the raw text was line-capped. Set includeRawSdf for the full record.",
+  "type": "number"
+}

addedOutput schema / properties / truncated

Added value: +{
+  "description": "True when the atom list, bond list, or raw SDF was capped below its total. atomCount/bondCount always report the full totals.",
+  "type": "boolean"
+}

Addedv0.2.2Jun 4, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations cover the safety profile (readOnly, idempotent, openWorld), and the description adds substantial behavior beyond them: the 200-atom/bond default truncation, the 500-line SDF cap, the disclosure enrichment on truncation, and that listing alternate conformers is noticeably slower. It also discloses the negative case where no conformer exists at all.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three front-loaded sentences that put the core purpose first and the caveats last. Some format explanation duplicates the schema description verbatim, which is mild redundancy, but nothing is wasted or padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return-shape explanation is unnecessary; the description instead covers the things an agent needs that structured fields don't convey — truncation defaults, the raw-SDF escape hatch, and the possibility that a valid CID simply has no 3D conformer.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description earns above-baseline credit by explaining the semantic split between format=json and format=sdf and by noting that alternate conformer IDs can be listed. It largely mirrors schema text for maxAtoms/maxBonds/includeRawSdf rather than adding new meaning, so it does not reach 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Get a compound's default 3D conformer — atomic coordinates and bonds — for one CID') and distinguishes itself from siblings like pubchem_get_compound_image, _details, and _xrefs by naming exactly what data is returned. An agent can identify this as the coordinate-retrieval tool without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear selection guidance between the two modes — json for parsed atoms/bonds, sdf 'for passthrough to docking, rendering, or conformer tools' — and flags the failure case ('Not every compound has computed 3D coordinates (large molecules, mixtures, and some salts do not)'). It stops short of explicitly routing to sibling tools when 3D data is unavailable or when the CID must first be resolved.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server