pubchem-mcp-server

---

概述

PubChem 中的化学化合物和生物测定。按名称、分子式或结构搜索化合物；获取属性、安全数据、生物活性、药物与食物相互作用、分子靶点和 3D 结构；并按生物靶点查找生物测定。

工具

工具	描述
pubchem_search_compounds	按名称、SMILES、InChI、InChIKey、分子式、子结构、超结构或二维相似性搜索化合物，或列出某项生物测定发现具有活性的化合物。
pubchem_get_compound_details	按 CID 获取化合物的理化性质、描述、同义词、类药性和分类信息。
pubchem_get_compound_image	按 CID 获取化合物的二维结构图（PNG）。
pubchem_get_compound_3d_structure	按 CID 获取化合物的三维构象（原子坐标和键），格式为已解析的 JSON 或原始 SDF。
pubchem_get_compound_xrefs	获取外部数据库交叉引用（PubMed、专利、基因、CAS 和 EC 编号等）。
pubchem_get_compound_safety	按 CID 获取一个或多个化合物的 GHS 危害分类和安全数据（批量）。
pubchem_get_bioactivity	获取化合物的生物活性概况：测定结果、靶标、活性值、测定类型和引用的 PubMed ID；可按结果、分子靶标或测定类型筛选。
pubchem_get_compound_interactions	获取化合物的药物-食物相互作用及其测定中提及的分子靶标，并列出各项的测定次数和最强活性值。
pubchem_search_assays	按生物靶标（基因符号、蛋白质、Gene ID、UniProt 登录号）查找生物测定。
pubchem_get_summary	获取 PubChem 实体的摘要：测定、基因、蛋白质、分类学。

资源

化合物和测定记录也会以 URI 模板资源的形式提供，底层使用与工具相同的客户端方法；许多 MCP 客户端仅支持工具，不会显示资源。

资源	描述
pubchem://compound/{cid}	核心理化性质（JSON）。
pubchem://compound/{cid}/safety	GHS 危害分类（JSON）。
pubchem://compound/{cid}/image	二维结构图（PNG）。
pubchem://compound/{cid}/xrefs	外部交叉引用（JSON）。
pubchem://compound/{cid}/bioactivity	生物测定活性概况（JSON）。
pubchem://assay/{aid}	BioAssay 摘要（JSON）。

能力参考

pubchem_search_compounds _工具

• 六种搜索策略：标识符（identifierType + identifiers；名称/SMILES/InChI/InChIKey，每次调用 25 个，其余返回在 unprocessed 中）、分子式（formula，Hill 表示法，可选 allowOtherElements）、子结构/超结构和二维相似性（query + queryType；相似性阈值为 70-100，默认为 90），或测定（aid；生物测定标记为活性的化合物，或使用 activeOnly: false 获取所有受测化合物）
• 每页最多返回 200 个 CID（默认为 20；更大的 maxResults 会按 200 提供，并在 cappedInputs 中报告）；offset 可将标识符和测定搜索分页至所有匹配结果，将分子式、子结构、超结构和相似性搜索分页至 10,000 条（更深页数会以 offset_ceiling_exceeded 失败）。可选的 properties 可省去后续调用 pubchem_get_compound_details
• 返回 totalFound；若上游搜索结果已达上限，则返回下限值 totalFoundAtLeast；对于没有 CID 的输入，返回 unresolvedIdentifiers。未知 AID 会报错 aid_not_found；PubChem 无法执行的查询会报错 search_query_rejected（并附带提示）

---

pubchem_get_compound_details _工具

• 每次调用最多处理 100 个 CID（其余返回在 unprocessed 中）；提供 27 项属性，默认返回其中 14 项核心属性
• 可选的描述（descriptionOffset/maxDescriptions，默认为 3，最多 20 条）和分类信息（FDA、MeSH、ATC）仅涵盖前 10 个 CID，其余列在 skippedCids 中。可选的同义词（synonymOffset/maxSynonyms，默认为 20，最多 100 个）和 Lipinski/Veber 类药性检查会涵盖所有找到的 CID
• 每个 CID 的 found: false 可区分不存在的 CID 与没有数据的化合物

---

pubchem_get_compound_image _工具

• 单个 CID；size 为 "small"（100x100）或 "large"（300x300，默认值）
• 返回经过 Base64 编码的 PNG，以及宽度和高度
• 如果 PubChem 中没有该 CID 的记录，则返回类型化的 cid_not_found 错误

---

pubchem_get_compound_3d_structure _工具

• 单个 CID；format="json"（默认值）返回已解析的原子（元素 + x/y/z）和键；format="sdf" 返回原始 V2000 SDF 文本
• maxAtoms/maxBonds 限制 JSON 预览内容（默认值均为 200）；atomCount/bondCount 始终报告完整总数，并通过补充信息说明是否进行了限制
• includeRawSdf 可绕过原始 SDF 文本默认的 500 行上限
• 可选的 includeAlternateConformerIds 会列出默认值之外的构象 ID
• 如果 PubChem 没有计算出的 3D 坐标（大型分子、混合物、某些盐类），则返回类型化的 no_3d_structure 错误

---

pubchem_get_compound_xrefs _工具

• 单个 CID；一个或多个 xrefTypes：CAS、EC、RN、RegistryID、PatentID、PubMedID、GeneID、ProteinGI、TaxonomyID
• CAS 和 EC 是为该化合物提交的编号，包含每个不同的值，并按提交该值的来源记录数量排序；这些数量列在 sourceCounts 中。RN 是 PubChem 未排序的注册号列表：CAS 号与已弃用及相关的 CAS RN 和 EC 编号并列
• PubChem 当前无法为 ProteinGI 返回数据；请使用 GeneID 查询基因/蛋白质关联
• maxPerType 最高为 500（默认值为 50），单个 offset 会应用于每种类型；每种类型都会报告 totalAvailable 和 truncated。PubMedID 按从新到旧的顺序排列
• 加载失败的类型会列在 failedTypes 中，其他类型仍会返回；只有当某种类型加载失败，且除 ProteinGI（PubChem 已不再提供）外没有任何类型加载成功时，调用才会失败。空结果会说明该化合物没有所请求的类型，或 CID 可能有误

---

pubchem_get_compound_safety _工具

• 每次调用最多处理 25 个 CID（其余 CID 会列在 unprocessed 中）
• 返回合并自多个来源的 GHS 信号词、象形图、H 代码和 P 代码，以及包含各来源自身标签的 classifications[]；预防性说明带有 decoded 标志
• 每个 CID 的 status 为：ok、not_classified（通知方未发现 GHS 危害）、no_ghs_data（没有提交的分类信息）或 cid_not_found，因此错误的 CID 不会被误报为“无危害记录”

---

pubchem_get_bioactivity _工具

• 单个 CID；可通过 outcomeFilter（active/inactive/all，默认值为 all）、targetGeneId/targetAccession 和 assayType（可为 confirmatory/screening/summary/other 中的任意值）筛选；测定必须通过所有已设置的筛选条件
• 靶标筛选条件会匹配与同一靶标关联的任何标识符，因此 Gene ID 5742、UniProt P23219 和 RefSeq NP_542158 都能找到相同的 COX-1 测定
• 每条结果都包含测定的 assayType 及其引用的 PubMed ID（pmids，按从新到旧的顺序排列）
• 每页最多返回 100 条结果（默认值为 20）；offset 可用于获取其余结果。针对多个靶标的测定会报告匹配的靶标，并将其他靶标列在 otherTargets 下
• 报告整个化合物的 totalAssays/activeCount/inactiveCount，以及当前页的 filteredCount/returnedCount；提示信息会说明无数据、筛选条件排除了所有结果，或 offset 超出结果范围

pubchem_get_compound_interactions _工具

• 单个 CID；一个或多个 kinds——drug-food（PUG View）、target、drug-drug（DrugBank）；默认为 ["drug-food"]，空的 drug-food 页面会指向 target
• target 会为化合物检测摘要中列出的每个靶标返回一条记录：一个 Gene ID 及表格与其配对的登录号，或一个表格从未与其配对的标识符。即使 Gene ID 和登录号指向同一种蛋白质，只要没有任何行将二者配对，它们就会作为单独的记录出现（厄洛替尼的 ERBB2 会分别显示为 accession:P04626 和 GeneID:2064）。每条记录会列出通过批量基因或蛋白质摘要查询获取的靶标名称，以及 pubchem_get_bioactivity 用于筛选的 GeneID: 或 accession: 值，并注明各结果的检测数量，以及效力最高的 Active 值和对应的 AID。Active 靶标排在前面，并按效力从高到低排序。如果名称查询失败，或几秒内没有响应，记录会保留标识符，并注明这一情况
• 每页每种类型的 maxEntries（上限为 50，默认为 10）；offset 按记录计数（target 中为靶标），最大为 2,147,483,646。每种类型单独分页，结果显示在 paging[]（totalRecords/nextOffset/truncated）中
• 失败的类型会列在 failedKinds 中，其他类型仍会返回。drug-drug 数据来自 PubChem 的 SDQ 服务，该服务会拒绝自动请求，因此它会列入 failedKinds，重试也无济于事

---

pubchem_search_assays _工具

• 按 targetType 搜索：genesymbol/proteinname（文本）、geneid（NCBI Gene ID）、proteinaccession（UniProt）
• 每页最多 200 个 AID（默认为 50）；offset 用于翻页浏览结果
• 如果 targetQuery 为空白，或 geneid 不是数字，则拒绝请求
• 返回 totalFound，并区分“无匹配项”和“offset 超出结果范围”

---

pubchem_get_summary _工具

• entityType：assay（AID）、gene（NCBI Gene ID）、protein（UniProt 登录号）或 taxonomy（Tax ID）；每次调用最多 10 个标识符
• 以逗号连接的字符串会拆分为多个标识符；超过前 10 个的部分会返回在 unprocessed 中，超过 1000 个时会以 too_many_identifiers 失败
• AID、Gene ID 和 Tax ID 必须是大于 0 且不超过 2147483647 的整数；其他部分会返回 invalid: true 的行，只有在没有任何可用标识符时，调用才会以 invalid_identifier 失败
• 每个标识符都有 found 标志；字段因 entityType 而异（taxonomy：有序的 lineage；gene：symbol/taxonomy；assay：method、前 25 个 targets 及 targetCount、已测试/活性化合物数量、lastDataChange）

---

pubchem://compound/{cid} _资源

• 核心理化性质（与 pubchem_get_compound_details 的默认 14 个属性集相同），格式为 application/json
• 如果 CID 在 PubChem 中不存在，则抛出类型化的未找到错误
• 如需选择特定属性或添加描述、同义词、类药性和分类信息，请使用 pubchem_get_compound_details

---

pubchem://compound/{cid}/safety _资源

• GHS 危害分类，格式为 application/json，包括各来源的 ghs.classifications 和贡献者 source 列表
• status（ok/not_classified/no_ghs_data/cid_not_found）是唯一能区分无效 CID 和未提交分类的化合物的信号——资源读取没有通知提示面

---

pubchem://compound/{cid}/image _资源

• 2D 结构图，300x300 PNG，以 base64 blob 的形式返回
• 如需 100x100 尺寸选项，请使用 pubchem_get_compound_image

---

pubchem://compound/{cid}/xrefs _资源

• 精简的默认集合——RN、RegistryID、PubMedID、CAS（含 sourceCounts）——每种类型最多 25 个 ID，格式为 application/json；PubMed ID 按分配时间从新到旧排列，返回最新分配的 25 个。无法加载的类型会列在 failedTypes 中
• 如需完整的交叉引用类型集合、提高每种类型的上限以及按偏移量分页，请使用 pubchem_get_compound_xrefs

---

pubchem://compound/{cid}/bioactivity _资源

• 以 application/json 返回最多 25 个测定结果，每个结果包含 assayType 和 pmids；还会返回整个化合物的 totalAssays/activeCount；多靶点测定会在 otherTargets 中列出其余靶点
• 使用 pubchem_get_bioactivity 按结果、靶点或测定类型筛选，提高上限，或使用偏移量分页

---

pubchem://assay/{aid} _资源

• 以 application/json 返回 BioAssay 摘要——名称、描述、来源、方案、物质数量
• 如果 AID 不存在，则抛出带类型的未找到错误

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可切换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），并支持结构化日志记录和可选的 OpenTelemetry 跟踪。

PubChem 专属功能：

• 覆盖 PUG REST 和 PUG View 端点，以及用于药物相互作用的 SDQ
• 具有限流功能的客户端（5 req/s），支持请求排队，并在发生暂时性故障时重试一次
• 每次调用的预算为 50 s；上游响应缓慢时会以 Timeout 失败，调用被取消时会以 RequestCancelled 失败
• 内置 V2000 SDF 解析器，可解析 3D 构象；药物相似性根据已获取的属性计算
• 所有工具均为只读且幂等，无需 API 密钥

适合 Agent 的输出：

• 每个 CID 都有 status 和 found 标志，调用方可据此判断数据，而不必匹配错误字符串
• 批量工具会返回各项结果，以及 unresolvedIdentifiers、skippedCids、failedKinds 和 failedTypes，而不是让整个调用失败
• 对列表进行截断时会注明 truncated、shown/cap 和 nextOffset；超出大小上限的批次会在上限范围内处理，其余部分通过 cappedInputs 和 unprocessed 报告
• 失败结果包含带类型的 reason（例如 cid_not_found、missing_identifier_args、invalid_cid_query）以及恢复提示

入门

公共托管实例

公共实例可通过 https://pubchem.caseyjhand.com/mcp 使用——无需安装。将任意 MCP 客户端通过 Streamable HTTP 指向该实例：

{
  "mcpServers": {
    "pubchem-mcp-server": {
      "type": "streamable-http",
      "url": "https://pubchem.caseyjhand.com/mcp"
    }
  }
}

自托管 / 本地

将以下内容添加到 MCP 客户端配置文件中。

{
  "mcpServers": {
    "pubchem-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/pubchem-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    }
  }
}

也可以使用 npx（无需 Bun）：

{
  "mcpServers": {
    "pubchem-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/pubchem-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    }
  }
}

也可以使用 Docker：

{
  "mcpServers": {
    "pubchem-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/pubchem-mcp-server:latest"]
    }
  }
}

要使用 Streamable HTTP，请设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前置条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 无需 API 密钥——PubChem 的 API 可免费访问。

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/pubchem-mcp-server.git

2. 进入目录：

cd pubchem-mcp-server

3. 安装依赖：

bun install

4. 配置环境（可选）：

cp .env.example .env
# edit .env to override transport, session mode, storage, or logging defaults

配置

变量	描述	默认值
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务的端口。	3010
MCP_HTTP_HOST	HTTP 服务的主机。	127.0.0.1
MCP_SESSION_MODE	stateless、stateful 或 auto。	stateless
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（RFC 5424）。	info
STORAGE_PROVIDER_TYPE	存储后端。	in-memory
OTEL_ENABLED	启用 OpenTelemetry。	false

完整的可选覆盖项列表见 .env.example。

运行服务

本地开发

• 构建并运行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t pubchem-mcp-server .
docker run --rm -p 3010:3010 pubchem-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/pubchem-mcp-server。默认会安装 OpenTelemetry 对等依赖；构建时使用 --build-arg OTEL_ENABLED=false 可省略这些依赖。

项目结构

目录	用途
src/index.ts	createApp() 入口点——注册工具和资源，并初始化 PubChem 客户端。
src/mcp-server/tools/definitions/	工具定义（*.tool.ts）。
src/mcp-server/resources/definitions/	资源定义（*.resource.ts）。
src/services/pubchem/	PubChem API 客户端——速率限制、重试以及响应/SDF 解析。
scripts/	构建、清理、开发检查和目录树生成脚本。
tests/	单元测试和集成测试。

开发指南

开发指南和架构规则请参阅 CLAUDE.md。简要说明：

• 处理程序抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 进行请求级日志记录
• 封装外部 API 调用：验证原始 PubChem 响应 → 规范化为领域类型 → 返回输出架构；绝不编造缺失字段
• 在 index.ts 汇总文件中注册新工具和资源

贡献

欢迎提交问题。提交前请运行检查：

bun run devcheck
bun run test

许可证

Apache-2.0——详情请参阅 LICENSE。