pubchem-mcp-server

---

概要

PubChem の化合物および生物活性試験を利用できます。化合物を名前、分子式、または構造で検索し、物性、安全性データ、生物活性、医薬品と食品の相互作用、分子標的、3D 構造を取得できます。また、生物学的標的を基に生物活性試験を検索できます。

ツール

ツール	説明
pubchem_search_compounds	名前、SMILES、InChI、InChIKey、分子式、部分構造、上位構造、または2D類似性で化合物を検索するか、バイオアッセイで活性ありと判定された化合物を一覧表示します。
pubchem_get_compound_details	CIDを指定して化合物の物理化学的性質、説明、同義語、医薬品適性、分類を取得します。
pubchem_get_compound_image	CIDを指定して化合物の2D構造図（PNG）を取得します。
pubchem_get_compound_3d_structure	CIDを指定して化合物の3D配座（原子座標と結合）を、解析済みJSONまたは生のSDFとして取得します。
pubchem_get_compound_xrefs	外部データベースへの相互参照（PubMed、特許、遺伝子、CAS番号、EC番号など）を取得します。
pubchem_get_compound_safety	CIDを指定して、1つ以上の化合物の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	2D構造図（PNG）。
pubchem://compound/{cid}/xrefs	外部相互参照（JSON）。
pubchem://compound/{cid}/bioactivity	バイオアッセイ活性プロファイル（JSON）。
pubchem://assay/{aid}	BioAssayの概要（JSON）。

機能リファレンス

pubchem_search_compounds _ツール

• 6種類の検索方法：識別子（identifierType + identifiers。名前／SMILES／InChI／InChIKey、1回の呼び出しにつき25件。残りはunprocessedで返されます）、分子式（formula、Hill表記法、任意のallowOtherElements）、部分構造／上位構造と2D類似性（query + queryType。類似性のしきい値は70～100、デフォルトは90）、またはアッセイ（aid。バイオアッセイで活性ありと判定された化合物、またはactiveOnly: falseの場合は検査対象の全化合物）
• 1ページあたり最大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 _ツール

• 1回の呼び出しにつき最大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 _tool

• CID は 1 つです。size は "small"（100x100）または "large"（300x300、デフォルト）です
• Base64 エンコードされた PNG と幅・高さを返します
• PubChem に CID のレコードがない場合は、型付きエラー cid_not_found を返します

---

pubchem_get_compound_3d_structure _tool

• CID は 1 つです。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 _tool

• CID は 1 つです。1 つ以上の xrefTypes を指定します：CAS、EC、RN、RegistryID、PatentID、PubMedID、GeneID、ProteinGI、TaxonomyID
• CAS と EC は、その化合物について登録された番号です。異なる値をすべて、登録したソースレコード数の多い順に返し、その件数を sourceCounts に含めます。RN は PubChem が順位付けせずに提供する登録番号の一覧です。CAS 番号のほか、廃止済みおよび関連する CAS RN と EC 番号も含まれます
• ProteinGI は現在 PubChem からデータを返しません。遺伝子／タンパク質との関連には GeneID を使用してください
• maxPerType は最大 500（デフォルトは 50）で、1 つの offset がすべてのタイプに適用されます。各タイプは totalAvailable と truncated を報告します。PubMedID は新しいものから順に返されます
• 読み込みに失敗したタイプは failedTypes に記載され、ほかのタイプは引き続き返されます。呼び出しが失敗するのは、タイプの読み込みに失敗し、かつ PubChem が現在提供していない ProteinGI 以外のタイプを読み込めなかった場合のみです。結果が空の場合は、要求したタイプのデータが化合物にないのか、CID の入力が誤っている可能性があるのかを示します

---

pubchem_get_compound_safety _tool

• 1 回の呼び出しにつき最大 25 個の CID を処理します（残りは unprocessed で返されます）
• ソース間で統合した GHS の注意喚起語、絵表示、H コード、P コードと、各ソース独自のラベルを含む classifications[] を返します。注意書きには decoded フラグが付きます
• CID ごとの status は ok、not_classified（届出者が GHS ハザードを見つけなかった）、no_ghs_data（分類情報の登録がない）、または cid_not_found です。そのため、誤った CID が「ハザード情報なし」と誤認されることはありません

---

pubchem_get_bioactivity _tool

• CID は 1 つです。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、新しいものから順）が含まれます
• 1 ページあたり最大 100 件（デフォルトは 20 件）で、offset を指定すると続きの結果を取得できます。複数のターゲットを対象とするアッセイでは、一致したターゲットを報告し、ほかのターゲットを otherTargets に一覧表示します
• 化合物全体の totalAssays／activeCount／inactiveCount と、ページの filteredCount／returnedCount を報告します。通知には、データがない場合、フィルターですべて除外された場合、または offset が末尾を超えている場合が示されます

---

pubchem_get_compound_interactions _tool

• 単一の CID。kinds は 1 つ以上指定します。指定できる値は drug-food（PUG View）、target、drug-drug（DrugBank）です。デフォルトは ["drug-food"] で、drug-food ページが空の場合は target を参照します
• target は、化合物のアッセイ概要に記載された標的ごとに 1 件を返します。Gene ID と、その表で組み合わされているアクセッション、または同じ行で組み合わされていない識別子です。同じタンパク質を示す場合でも、どの行でも組み合わされていない Gene ID とアクセッションは別々の項目になります（エルロチニブの ERBB2 は accession:P04626 と GeneID:2064 として表示されます）。各項目には、遺伝子またはタンパク質の一括概要検索で取得した標的名、pubchem_get_bioactivity がフィルタリングに使用する GeneID: または accession: の値、結果別のアッセイ件数、および AID とともに最も強力な Active 値が記載されます。Active の標的は、最も強力なものから順に表示されます。名前の検索に失敗した場合、または数秒以内に結果が返らない場合は、項目には識別子が保持され、その旨が通知されます
• ページあたり、種類ごとの maxEntries（最大 50、デフォルト 10）を指定します。offset はレコード（target の場合は標的）の件数で指定し、上限は 2,147,483,646 です。種類ごとに独立してページ分割され、結果は paging[]（totalRecords／nextOffset／truncated）に報告されます
• 取得に失敗した種類は failedKinds に記載され、ほかの種類の結果は引き続き返されます。drug-drug は PubChem の SDQ サービスから取得されますが、このサービスは自動リクエストを拒否するため、failedKinds に含まれます。再試行しても解決しません

---

pubchem_search_assays _tool

• targetType で検索します。genesymbol／proteinname（テキスト）、geneid（NCBI Gene ID）、proteinaccession（UniProt）を指定します
• 1 ページあたり最大 200 件の AID を返します（デフォルト 50）。offset で結果をページ移動します
• 空の targetQuery と、数値以外の geneid は拒否されます
• totalFound を報告し、「一致なし」と「終端を超える offset」を区別します

---

pubchem_get_summary _tool

• entityType は assay（AID）、gene（NCBI Gene ID）、protein（UniProt アクセッション）、または taxonomy（Tax ID）を指定します。1 回の呼び出しで最大 10 件の識別子を指定できます
• カンマ区切りの文字列は識別子に分割されます。先頭から 10 件を超える分は unprocessed で返され、1000 件を超えると too_many_identifiers として失敗します
• AID、Gene ID、Tax ID は、2147483647 以下の正の整数である必要があります。それ以外の要素は invalid: true の行として返され、使用可能な識別子が 1 件もない場合に限り、呼び出しは invalid_identifier として失敗します
• 識別子ごとの found フラグを返します。フィールドは entityType によって異なります（taxonomy：順序付きの lineage、gene：symbol／taxonomy、assay：method、先頭 25 件の targets と targetCount、試験済み／活性化合物の件数、lastDataChange）

---

pubchem://compound/{cid} _resource

• 主要な物理化学的特性を application/json で返します（pubchem_get_compound_details と同じデフォルトの 14 特性セット）
• CID が PubChem に存在しない場合は、型付きの Not Found エラーをスローします
• 特定の特性を選択する場合や、説明、同義語、薬剤類似性、分類を追加する場合は pubchem_get_compound_details を使用します

---

pubchem://compound/{cid}/safety _resource

• GHS 危険有害性分類を application/json で返します。ソースごとの ghs.classifications と、提供者の source リストを含みます
• PubChem に登録された分類のない化合物と、無効な CID を区別する唯一の手掛かりは status（ok／not_classified／no_ghs_data／cid_not_found）です。リソースの読み取りには通知を表示する仕組みがありません

---

pubchem://compound/{cid}/image _resource

• 2D 構造図を 300x300 の PNG として、base64 blob で返します
• 100x100 のサイズを指定する場合は pubchem_get_compound_image を使用します

---

pubchem://compound/{cid}/xrefs _resource

• デフォルトでは対象を絞ったセット（RN、RegistryID、PubMedID、CAS。sourceCounts を含む）を、種類ごとに最大 25 件、application/json で返します。PubMed ID は割り当て日時が新しいものから 25 件を返します。読み込みに失敗した種類は failedTypes に記載されます
• すべての xref 種類、種類ごとの上限数の引き上げ、offset によるページ分割には 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）を備え、リクエストをキューに登録し、一時的な障害時には1回再試行します。
• 呼び出しごとに50秒の制限時間を設けており、上流処理が遅い場合はTimeoutとして失敗します。キャンセルされた呼び出しはRequestCancelledとして失敗します。
• 3Dコンフォマー用のV2000 SDFパーサーを内蔵しています。薬物類似性は取得済みのプロパティから計算されます。
• すべてのツールは読み取り専用かつ冪等で、APIキーは不要です。

エージェント向けの出力：

• 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で利用できます。インストールは不要です。Streamable HTTPを介して、任意のMCPクライアントから接続できます。

{
  "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 のバレルファイルに登録してください

コントリビューション

Issue を歓迎します。提出前にチェックを実行してください。

bun run devcheck
bun run test

ライセンス

Apache-2.0 — 詳細については LICENSE を参照してください。