pubchem-mcp-server

Get Compound 3D Structure

pubchem_get_compound_3d_structure

Read-onlyIdempotent

Retrieve a compound's 3D atomic coordinates and bonds from PubChem by CID. Choose JSON for parsed data or SDF for raw docking-ready output.

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.

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.1/5.0

Behavior4/5

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

Annotations already declare readOnly, idempotent, and openWorld hints. The description adds useful behavioral context beyond these: format differences (parsed JSON vs. raw SDF), the caveat that not every compound has 3D coordinates, and performance notes (alternate conformer listing is slower). It also discloses truncation behavior in the parameter descriptions, which is behaviorally relevant. No contradictions with annotations.

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?

The description is two sentences that front-load the core purpose and then add important qualifications (format options, missing-coordinate caveat). It is efficient without being terse, and every sentence adds value. Some redundancy with the schema exists, but the description remains appropriately sized.

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

Completeness4/5

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

Given the output schema exists, the description does not need to explain return values. It covers the main behavior, both format options, and a key failure mode (missing 3D coordinates). It doesn't explicitly state what happens on a missing conformer, but that could be in the output schema. Overall, it is complete for the tool's complexity.

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

Parameters3/5

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

Schema description coverage is 100% – every parameter already has a clear description in the schema. The tool's description does not add meaning beyond what the schema provides (e.g., it recaps format behavior but that's also in the schema). Therefore, baseline 3 is appropriate; the schema does the heavy lifting.

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?

The description states a specific verb and resource: 'Get a compound's default 3D conformer — atomic coordinates and bonds — for one CID.' This clearly distinguishes it from sibling tools like pubchem_get_compound_details or pubchem_get_compound_image, which focus on other aspects. The scope ('for one CID') adds precision.

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?

The description provides clear context about what the tool does and its format options, but it does not explicitly name alternatives or state when to use this tool versus a sibling. However, it implies usage by its specificity (3D structure) and includes a caveat about missing coordinates, which helps set expectations. The lack of explicit exclusions prevents a score of 5.

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

Deploy Server