cdc-health-mcp-server

---

概要

CDC Open Data ポータルおよび CDC WONDER の公衆衛生データを提供します。予防接種、サーベイランス、行動リスクに関する 1,000 件以上のデータセットを検索し、スキーマを調べて SoQL で照会できます。また、年、年齢、性別、人種別の全国死亡統計を取得できます。

ツール

ツール	説明
cdc_discover_datasets	キーワード、カテゴリ、タグで CDC データセットカタログを検索します
cdc_get_dataset_schema	データセットの列スキーマ、行数、メタデータを取得します
cdc_list_catalog_vocabulary	カタログのカテゴリとタグの値を、各項目の登録数とともに一覧表示します
cdc_query_dataset	SoQL クエリを実行します — フィルタリング、集計、並べ替え、全文検索、フィールド選択に対応します
cdc_query_wonder	CDC WONDER に問い合わせ、5 つのデータベースを対象に全国の死亡数、人口、死亡率を取得します

リソース

リソース	説明
cdc://datasets	閲覧数上位 50 件のカタログ項目。概要の把握に利用できます
cdc://datasets/{datasetId}	特定のデータセットのメタデータと最初の 100 列

どちらのリソースも、cdc_discover_datasets および cdc_get_dataset_schema からも取得できるデータを提供します。リソースには対応しているものの、ツールには対応していないクライアント向けです。

プロンプト

プロンプト	説明
analyze_health_trend	CDC データを横断して公衆衛生上の課題を調査するためのガイド付きワークフロー

機能リファレンス

cdc_discover_datasets _ツール

• フィルター：query、category、tags。1ページあたり最大100件（デフォルトは10件）。offset + limit の上限は10,000件で、それを超えると page_out_of_range になります。order は dataset_id（デフォルト。安定したページングが可能）または relevance です
• 結果には assetType、columnCount（0はグラフ、マップ、その他の非表形式アセットを示します）、8個の名前を含む columnSample、300文字に切り詰めた説明に加え、totalCount と appliedFilters が含まれます
• category または tags の値に一致するものがない場合、notice には最も近いカタログ値と、その項目数が表示されます。例：Vaccination → "Vaccinations" (89 datasets)

---

cdc_get_dataset_schema _ツール

• 4文字、ハイフン、4文字の形式の datasetId を指定します（例：bi63-dtpu）。column_limit（デフォルトは100）と column_offset で列数の多いスキーマをページ分割し、totalCount、truncated、nextOffset を返します
• データセットの description はデフォルトで最大4,000文字です。切り詰められた場合は descriptionTruncated と descriptionLength が設定されます。full_description: true を指定すると、テキスト全体が返されます
• 列には fieldName、dataType、description が含まれます。rowCountSource は rowCount が live の値か、Socrata の cached の値かを示します。非表形式アセットを指定すると not_queryable が返されます

---

cdc_list_catalog_vocabulary _ツール

• カテゴリはすべて返されます。約1,600件のタグは項目数の多い順に並べられ、tag_limit（デフォルトは50）と tag_offset でページ分割されます。filter（3文字以上）を指定すると、あいまい検索ではなく単語の一致によってカテゴリとタグの両方が絞り込まれます
• 各値には datasetCount が含まれます。レスポンスには vocabularySize、categoryCount、tagCount、truncated、nextOffset、およびページ以降のタグ数の上限を示す truncationCeiling も含まれます

---

cdc_query_dataset _ツール

• 句：select、where、group、having、order、全文検索の search。1回の呼び出しで最大5,000行（デフォルトは100行）を取得でき、offset の上限は1,000,000です
• 安定したオフセットページングを行うには、order の末尾に一意のタイブレーカーを指定します（グループ化していない行では :id、グループ化したクエリではグループ化対象の列）。指定がない場合は notice にその旨が記載されます
• effectiveQuery は送信された SoQL の句をそのまま返します。ページングの状態は truncated と nextOffset で示され、totalCount はありません。グラフまたはマップの ID を指定すると not_queryable が返されます

---

cdc_query_wonder _ツール

database	CDC データベース	年	人種グループ	mcd_icd10
underlying_1999_2020 (デフォルト)	D76 — 死亡の基礎原因	1999–2020	4（ブリッジ方式）	—
provisional	D176 — 暫定死亡統計	2018年 → 現在の年	6（単一人種）	yes
underlying_2018_2024	D158 — 死亡の基礎原因、単一人種	2018–2024	6（単一人種）	—
multiple_1999_2020	D77 — 死亡の複数原因	1999–2020	4（ブリッジ方式）	yes
multiple_2018_2024	D157 — 死亡の複数原因、単一人種	2018–2024	6（単一人種）	yes

• group_by には year、age_group、sex、race（全米のみ）のうち1～4個を指定します。cause_icd10 と mcd_icd10 には ICD-10 コード、範囲（X40-X49）、または最大50件のリストを指定します。age_groups には NS（年齢不詳）を単独で指定するか、既知の11グループすべてとともに指定します。limit と offset（最大10,000）でテーブルをページ分割します
• 行には deaths、population、crude_rate、および年齢標準化が可能な場合は age_adjusted_rate が含まれます。CDC が Suppressed、Unreliable、Not Applicable として返すセルは null として読み込まれ、cellNotes に記載されます。CDC が非表示にした行は messages に報告され、totalCount は正確な件数です
• CDC は15秒未満の間隔で送信されたリクエストを拒否するため、呼び出しはキューに入れられ、1回ずつ16秒間隔で実行されます

---

cdc://datasets _リソース

• 人気順のカタログ上位50件。それぞれに id、name、assetType、category、columnCount、updatedAt が含まれ、カタログの totalCount も返されます
• columnCount: 0 は非表形式の項目を示します。カタログ全体の検索とページ分割には cdc_discover_datasets を使用します

---

cdc://datasets/{datasetId} _リソース

• application/json 形式のデータセットメタデータと最初の100列。columnCount と truncated を含み、説明は4,000文字までです
• さらに多くの列や完全な説明を取得するには、column_offset または full_description: true を指定して cdc_get_dataset_schema を使用します

---

analyze_health_trend _{プロンプト}

• 引数：topic は必須、timeRange と geography は任意です
• 質問を cdc_query_wonder（全米の死亡統計）または Socrata ツール（それ以外すべて）に振り分け、discover → inspect → baseline → compare → synthesize の順に進めるユーザーメッセージを1件返します

機能

@cyanheads/mcp-ts-core を基盤としており、stdio と Streamable HTTP のトランスポート、切り替え可能な認証（none / jwt / oauth）、交換可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、およびオプションの OpenTelemetry トレース機能を備えた構造化ログを提供します。

CDC 固有の機能：

• CDC Open Data ポータルの約1,080件のデータセットを対象とする Socrata SODA API v2.1 を使用します。認証は不要で、アプリトークンを設定するとレート制限が緩和されます
• 1999年から現年までを対象とする5つのデータベースから、XML リクエスト API 経由で CDC WONDER の死亡統計データを取得します
• 3つの Socrata ツールは domain 入力を受け付けます。指定できるのは data.cdc.gov（デフォルト）と chronicdata.cdc.gov に限られ、どちらも同じカタログを提供します
• category と tags はカタログ内の値と一致させる必要があります（カテゴリは大文字と小文字を区別し、タグは区別しません）。値は cdc_list_catalog_vocabulary で確認できます
• Socrata はすべての値を文字列として返します。また、year などの列は、データセットによって数値の場合とテキストの場合があります。WHERE リテラルは列の dataType に合わせてください。数値はクォートなし、文字列はシングルクォートで囲みます

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

• ページング情報を明示します：totalCount、truncated、nextOffset、shown/cap。どちらのクエリツールも1ページあたり200,000文字を上限とするため、列数の多いページでは limit より少ない件数で終了することがあります
• not_queryable、page_out_of_range、invalid_query など、宣言されているすべての理由について、復旧のヒントを含む型付きエラーを返します
• 上流データの欠落も確認できます。WONDER のステータストークンは cellNotes に、非表示行の通知は messages に表示され、スキーマの行数には rowCountSource が付与されます
• effectiveQuery には SoQL の句または WONDER のクエリ概要が記録され、結果を再現できます

はじめに

公開ホストインスタンス

公開インスタンスは https://cdc.caseyjhand.com/mcp で利用できます。インストールは不要です。Streamable HTTP 経由で任意の MCP クライアントから接続してください：

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

セルフホスト／ローカル

以下を MCP クライアントの設定ファイルに追加します。

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

または npx を使用します（Bun は不要です）：

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

または Docker を使用します：

{
  "mcpServers": {
    "cdc-health-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/cdc-health-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+）。
• 任意：Socrata アプリトークン。レート制限を緩和できます。

インストール

1. リポジトリをクローンします：

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

2. ディレクトリに移動します：

cd cdc-health-mcp-server

3. 依存関係をインストールします：

bun install

4. 環境を設定します：

cp .env.example .env
# optionally set CDC_APP_TOKEN

構成

変数	説明	デフォルト
CDC_APP_TOKEN	Socrata アプリトークン。レート制限が緩和されます。	なし
CDC_BASE_URL	domain が指定されていないリクエスト（cdc://datasets/{datasetId} リソース）に使用する SODA ホスト。	https://data.cdc.gov
CDC_CATALOG_URL	Socrata Discovery API のベース URL。	https://api.us.socrata.com/api/catalog/v1
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_HTTP_PORT	HTTP サーバーのポート。	3010
MCP_SESSION_MODE	HTTP セッションモード：stateless、stateful、または auto。	stateless
MCP_AUTH_MODE	認証：none、jwt、または oauth。	none
MCP_LOG_LEVEL	ログレベル（debug、info、warning、error など）。	info
OTEL_ENABLED	OpenTelemetry を有効にします。	false

任意のオーバーライド設定の一覧については、.env.example を参照してください。

サーバーの実行

ローカル開発

• 本番バージョンをビルドして実行する：

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

• チェックとテストを実行する：

  bun run devcheck  # Lints, formats, type-checks, and more
  bun run test      # Runs the test suite
  

Docker

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

Dockerfile のデフォルトでは、HTTP トランスポート、ステートレスセッションモードを使用し、ログを /var/log/cdc-health-mcp-server に出力します。OpenTelemetry のピア依存関係はデフォルトでインストールされます。これらを省略するには、--build-arg OTEL_ENABLED=false を指定してビルドしてください。

プロジェクト構成

ディレクトリ	用途
src/index.ts	createApp() のエントリーポイント — ツール、リソース、プロンプトを登録し、サービスを初期化します。
src/config	サーバー固有の環境変数の解析と、Zod による検証を行います。
src/mcp-server/tools	ツール定義（*.tool.ts）。Socrata のツールが 4 つ、WONDER のツールが 1 つあります。
src/mcp-server/resources	リソース定義。カタログの概要とデータセットの詳細です。
src/mcp-server/prompts	プロンプト定義。健康トレンド分析のワークフローです。
src/services/socrata	Socrata サービス — カタログ検索、語彙、メタデータ、SoQL クエリを扱います。
src/services/wonder	CDC WONDER サービス — XML リクエストビルダー、レスポンスパーサー、リクエスト間隔を扱います。
src/utils	共有ヘルパー — HTML からテキストへの変換、テーブルセルのエスケープ、語彙の照合、レスポンス予算を扱います。
tests/	src/ の構成に対応する単体テストと統合テストです。

開発ガイド

開発ガイドラインとアーキテクチャ上のルールについては、CLAUDE.md を参照してください。要点は次のとおりです。

• ハンドラーは例外をスローし、フレームワークが捕捉します — ツールのロジックで try/catch を使用しないでください
• ロギングには ctx.log、ストレージには ctx.state を使用してください
• 新しいツールとリソースは、src/index.ts の createApp() 配列に登録してください
• 外部 API 呼び出しをラップしてください：生データを検証 → ドメイン型に正規化 → 出力スキーマを返す。欠落フィールドを決して捏造しないでください

コントリビューション

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

bun run devcheck
bun run test

ライセンス

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