snowstorm-mcp-server

SNOMED CT の臨床用語を Snowstorm および Snowstorm Lite バックエンド経由で照会するための MCP サーバーです。

SNOMED CT は世界で最も包括的な臨床用語体系であり、80 か国以上の電子カルテで使用されています。このサーバーは、Model Context Protocol (MCP) を通じて SNOMED CT の照会、検索、検証、階層ナビゲーション、値セット展開を公開し、AI アシスタントが臨床用語を直接扱えるようにします。

接続先バックエンドで利用可能なすべての SNOMED CT エディション（国際版、米国版、英国版、豪州版など）をサポートします。公開 Snowstorm インスタンスに接続する場合、ユーザーアカウントは不要です。

このリポジトリは、関連するが異なる 2 つの利用モードをサポートしています。

1. ホスト型リモートコネクタ: 公開 HTTPS MCP エンドポイントを実行し、カスタムコネクタ / Connector Directory フローを介して Claude を接続します。

2. セルフホストまたはローカル利用: 独自の Snowstorm または Snowstorm Lite デプロイに対してサーバーを自分で実行します。Claude Desktop や将来の MCPB パッケージングシナリオを含みます。

Claude web/desktop/mobile 用のホスト型コネクタを準備する場合は、ホスト型リモートコネクタ から始めてください。独自の用語バックエンドに対してサーバーを自分で実行する場合は、セルフホストおよびローカル利用 から始めてください。

ホスト型リモートコネクタ

このモードは、https://your-domain.example/mcp などの公開 MCP エンドポイントを運用し、Anthropic のインフラストラクチャから Claude に接続させたい場合に使用します。

ホスト型デプロイ（Docker）

コンテナをビルドして実行します:

docker build -t snowstorm-mcp-server .
docker run -p 8000:8000 --memory=512m --restart=unless-stopped snowstorm-mcp-server

--memory を設定してください。cgroup 制限がないと、コンテナはカーネルのグローバル OOM キラーが作動するまで成長し続け、その際にホスト上で最も大きなプロセスが選ばれます。つまり、このサーバーの障害がコンテナだけでなくホスト全体をダウンさせてしまいます。制限を設定すれば、コンテナだけが強制終了され、--restart によってすぐに復帰します。

サーバーは、バンドルされている config.docker-snowstorm.yaml を使用して、ポート 8000 で Streamable HTTP モードで起動します（http://localhost:8080 のローカル Snowstorm を想定）。実行時に独自の設定をマウントします:

docker run -p 8000:8000 \
  -v /path/to/your/config.yaml:/app/config.yaml \
  snowstorm-mcp-server

本番環境では、HTTPS リバースプロキシの背後にデプロイするか、自動 TLS を備えたプラットフォーム（Cloud Run、Fly.io、Railway など）にデプロイしてください。公開向けデプロイでは、リバースプロキシでクライアントごとのレート制限（IP ベース）を設定してください。MCP 2026-07-28 でプロトコルレベルのセッションが削除されたため、アプリケーションレベルのセッションごとの制限は HTTP クライアントには適用されなくなりました。グローバル制限は依然としてバックエンド全体の負荷を制限します。詳細は下記のパフォーマンスガードを参照してください。

Claude web/desktop 向けのリモート MCP コネクタデプロイでは、サーバーはデフォルトで Streamable HTTP エンドポイント上の https://claude.ai と https://claude.com に対して CORS を有効にします。必要に応じて、SNOWSTORM_MCP_CORS_ALLOW_ORIGINS 環境変数で許可オリジンリストをカンマ区切りで上書きできます。

オリジン検証はデフォルトで有効です。 MCP エンドポイントへのリクエストで Origin ヘッダーが存在するが許可リストにない場合、HTTP 403 で拒否されます。これが DNS リバインディングを防ぐ仕組みです。リバウンドされたページの POST は、Fetch Standard に従って、ブラウザがすべての POST（同一オリジンのものも含む）に Origin を付加するため、実際のオリジンを保持します。Origin をまったく送信しないリクエスト（すべての非ブラウザ MCP クライアントが該当）は影響を受けません。

これは現在のすべてのブラウザエンジンに当てはまります。Firefox 103 以前（2022 年 7 月）は、特に network.http.sendOriginHeader 設定が無効になっている場合、null ではなく Origin 自体を省略することがありました。そのようなクライアントが対象範囲に含まれる場合は、SNOWSTORM_MCP_ALLOWED_HOSTS も設定してください。

許可リストはデフォルトで上記の CORS オリジンになります。リバースプロキシ背後での同一オリジンデプロイ（CORS はオフだがブラウザの POST は依然として Origin を運ぶ）では、SNOWSTORM_MCP_ALLOWED_ORIGINS（カンマ区切り）で独立して上書きできます。これはリストに追加するのではなく置き換えるため、提供するすべてのブラウザオリジンを含めてください。自分のドメインだけに設定すると https://claude.ai がロックアウトされます。* に設定するとアプリレベルのチェックが無効になります。SNOWSTORM_MCP_ALLOWED_HOSTS も設定されている場合、SDK レイヤーが CORS リストに対して Origin を引き続き検証することに注意してください。

アップグレードに関する注意: ページオリジンが許可リストにないブラウザクライアントは、以前は成功していたリクエストが CORS 設定に関係なく 403 を受け取るようになりました。CORS はこれらのリクエストを拒否したのではなく、レスポンスヘッダーを付与しなかっただけであり、同一オリジンの読み取りはそもそも CORS の対象外でした。独自の Web UI を提供するセルフホストデプロイでは、SNOWSTORM_MCP_ALLOWED_ORIGINS をそのオリジンに設定するか、以前の動作を復元するために * に設定する必要があります。非ブラウザクライアントは Origin を送信しないため影響を受けません。

SNOWSTORM_MCP_ALLOWED_HOSTS を、サーバーが到達可能なホスト名（カンマ区切り、例: mcp.example.org,mcp.example.org:443）に設定すると、認識されない Host を HTTP 421 で追加で拒否します。これはデフォルトではオフのままです。ホストリストが不完全だとすべてのトラフィックが拒否されるためです。localhost にバインドする場合は自動的に有効になります。これは多層防御です。上記の Origin 検証が、この POST 専用エンドポイントのリバインディング経路をすでに塞いでいます。

MCP プロトコルバージョン

サーバーは 2 つの時代に対応しています。ステートレスの MCP 2026-07-28 リビジョンと、それ以前のハンドシェイクベースのリビジョン（2025-11-25 以前）の両方を同じエンドポイントで提供するため、既存のクライアントは引き続き動作します。どちらの場合もステートレスで動作し、Mcp-Session-Id を発行しないため、セッションアフィニティなしで水平スケーリングできます。

リモートコネクタの注意事項

• Anthropic はホスト型 MCP エンドポイントに自社のクラウドインフラストラクチャから接続します。

• Anthropic は base_url、user_agent、ターゲット認証などの内部 Snowstorm バックエンド設定を設定しません。これらはサーバー設定に残ります。

• このリポジトリの manifest.json はローカルパッケージングシナリオ用であり、ホスト型リモートコネクタフロー用ではありません。

Related MCP server: Smart EHR MCP Server

セルフホストおよびローカル利用

このモードは、独自の Snowstorm または Snowstorm Lite バックエンドに対して MCP サーバーを自分で実行したい場合に使用します。ローカル、プライベートインフラストラクチャ、または Claude Desktop / MCPB スタイルのパッケージングのいずれでも構いません。

開発クイックスタート

uv venv
uv pip install -e ".[dev]"
uv run pytest -q
./scripts/check.sh

ユニットテストと統合テストのワークフロー（Docker スタックのセットアップや RF2 インポートを含む）については、docs/testing.md を参照してください。

Docker 統合スタック（Snowstorm + Lite）

統合テスト用のローカルコンテナを起動します:

docker compose -f docker-compose.integration.yml up -d

ローカルの RF2 アーカイブを Snowstorm と Snowstorm Lite の両方にインポートします:

dev/integration/import_snomed.sh \
  --rf2-zip ../SnomedCT_InternationalRF2_PRODUCTION_20251101T120000Z.zip

各バックエンドに対して統合テストを実行します。.env の SNOWSTORM_MCP_TEST_CONFIG を該当する設定ファイルを指すように設定してから:

uv run pytest -q tests/integration

サーバーをローカルで実行する

サーバーは YAML ファイルから設定を読み取ります（example-configs/config.local.yaml を参照）。プロジェクトルートに .env ファイルを作成し、設定パスと任意のシークレットを設定します（.env.example を参照）:

cp .env.example .env
# edit .env to point at your config file

サーバーは起動時にカレントワーキングディレクトリから .env を自動的に読み込みます。既存のシェル環境変数は .env の値よりも優先されます。

stdio（Claude Desktop およびほとんどの MCP クライアント向け）:

uv run snowstorm-mcp-server --transport stdio

--log-level DEBUG|INFO|WARNING|ERROR を使用して詳細度を制御します（デフォルト: INFO）。ログは stderr に出力され、Claude Desktop によって mcp-server-snowstorm.log にキャプチャされます。サーバーは起動時にアクティブなガード設定を出力するため、正しい設定ファイルから設定が読み込まれていることを確認できます。

ロギング

デフォルトでは、サーバーは UTC タイムスタンプ付きの JSON オブジェクトを 1 行に 1 つログ出力します。ログ集約ツールが直接解析できます:

{"timestamp": "2026-07-13T10:29:04.929Z", "level": "ERROR", "logger": "snowstorm_mcp_server.mcp_app", "message": "Tool call failed [E_BACKEND_HTTP]: HTTP 502 ...", "error_code": "E_BACKEND_HTTP", "error_type": "HttpRequestError", "status_code": 502}

ツールの失敗には構造化フィールド（error_code、error_type、status_code）が含まれるため、エラーレートを原因別に分類できます。ガードの作動（レート制限、ECL ブロック、トラバーサル検出）は警告としてログに記録されます。ローカル開発中は、従来の人間が読みやすい出力のために --log-format text を使用してください。

Streamable HTTP（HTTP ベースの MCP クライアント向け）:

uv run snowstorm-mcp-server --transport streamable-http

スタンドアロンの sse トランスポートは Streamable HTTP に置き換えられて削除されました。HTTP+SSE トランスポートは MCP 2025-03-26 以降非推奨であり、2026-07-28 時点で機能ライフサイクルポリシーに基づき正式に Deprecated となっています。

Claude Desktop 設定例（~/Library/Application Support/Claude/claude_desktop_config.json）:

{
  "mcpServers": {
    "snowstorm": {
      "command": "uv",
      "args": [
        "run",
        "--project", "/path/to/snowstorm-mcp-server",
        "snowstorm-mcp-server",
        "--transport", "stdio"
      ]
    }
  }
}

注: Claude Desktop はプロジェクトディレクトリから uv を実行するため、.env ファイルを自動的に読み込みます。明示的な環境変数を希望する場合は、Claude Desktop 設定の "env" キーで渡してください。

ローカルパッケージング / MCPB インストール

Connector Directory エントリからサーバーをインストールする場合、マニフェストは設定ファイルのパスを求め、起動時に --config として渡します。ローカル開発には example-configs/ 内の YAML ファイルのいずれかを選択するか、独自の Snowstorm / Snowstorm Lite デプロイ設定へのパスを指定してください。

設定

example-configs/config.local.yaml を参照してください（http://localhost:8080 の Snowstorm）。

バックエンドタイプの制限

1 つの設定は Snowstorm または Snowstorm Lite ターゲットのいずれかを使用する必要があります。同じ設定に両方を混在させることはできません。server_mode フィールドはターゲットタイプと一致している必要があります（Snowstorm ターゲットの場合は "snowstorm"、Lite ターゲットの場合は "lite"）。

複数の Snowstorm Lite インスタンスがサポートされています（SNOMED エディションごとに 1 つ）。

複数エディション Lite 設定例

server_mode: "lite"
default_terminology: snomedct
response_limits:
  max_expand_contains: 100
  max_search_hits: 50
  max_synonyms: 25

# Guards — all values shown are defaults. Omit the block to use defaults.
# For public-facing HTTP deployments, do per-client limiting at the reverse
# proxy: MCP 2026-07-28 removed sessions, so per_session_rate_limit_calls
# only has an effect on stdio.
# guards:
#   rate_limit_calls: 10
#   rate_limit_window_seconds: 60
#   max_concurrent_requests: 3
#   max_count_per_call: 500
#   large_result_threshold: 1000
#   max_children_calls_per_minute: 5
#   per_session_rate_limit_calls: null   # stdio only; no effect over HTTP
#   block_zero_cardinality_on_large_sets: false  # set true to block [0..0] on top-level roots
#   enable_expansion_size_guard: false   # preflight summary check for any non-summary expansion
#   expansion_count_threshold: 20000     # block if total concepts exceeds this value
#   size_cache_ttl_seconds: 86400

targets:
  lite-int:
    base_url: "http://localhost:8081"
    mode: "lite"
    terminology_name: "snomedct"
    fhir_path: "/fhir"
    auth:
      mode: "none"

  lite-us:
    base_url: "http://localhost:8082"
    mode: "lite"
    terminology_name: "snomedct-us"
    fhir_path: "/fhir"
    auth:
      mode: "bearer"
      token: "${SNOWSTORM_LITE_TOKEN}"

用語ベースのルーティング

このサーバーは、バックエンドターゲットではなく用語体系（SNOMED エディション）によってリクエストをルーティングします。

• Snowstorm: 用語体系は GET /codesystems から自動検出されます。各コードシステムの shortName（小文字化）が用語体系名になります（例: snomedct、snomedct-us）。ネイティブの Snowstorm 操作にはブランチパスが自動的に使用されます。

• Snowstorm Lite: 各インスタンスは 1 つの用語体系を提供します。ターゲット設定で terminology_name を設定してください。

デフォルト用語体系

設定で default_terminology を設定すると、呼び出し側は terminology パラメータを省略できます。利用可能な用語体系が 1 つだけの場合は、自動的にデフォルトになります。

利用可能な MCP ツール

すべてのツールはオプションのterminologyパラメータ（例："snomedct-us"）を受け付けます。 ほとんどのツールは、ルーティングを制限／ターゲット選択を明確化するためのオプションのtargetも受け付けます。 省略した場合は、デフォルトの用語集が使用されます。

環境変数によるシークレットの上書き

シークレットは値をコミットする代わりに、環境変数を使って実行時に注入できます：

• 設定ファイル内のプレースホルダー補間：${ENV_VAR} または ${ENV_VAR:-default}

• ターゲット認証シークレットの上書き変数：

  • SNOWSTORM_MCP_TARGETS__<TARGET_NAME_UPPER>__AUTH__PASSWORD

  • SNOWSTORM_MCP_TARGETS__<TARGET_NAME_UPPER>__AUTH__TOKEN

MCPツール呼び出しのサンプル

list_terminologies：

{}

期待されるレスポンス形式：

{
  "terminologies": [
    {"name": "snomedct", "backend_type": "snowstorm", "branch_path": "MAIN"},
    {"name": "snomedct-us", "backend_type": "lite", "branch_path": null}
  ],
  "default_terminology": "snomedct"
}

server_capabilities（デフォルトの用語集）：

{}

期待されるレスポンス形式：

{
  "terminology": "snomedct",
  "backend_type": "snowstorm",
  "reachable": true,
  "fhir_base_url": "http://localhost:8080/fhir",
  "capabilities": {"has_fhir": true, "has_native_api": true, "has_lite_load_package": false},
  "fhir_metadata_summary": {"resourceType": "CapabilityStatement", "fhirVersion": "4.0.1"}
}

fhir_metadata サマリーのみモード（生のCapabilityStatement本文を省略）：

{"terminology": "snomedct", "include_raw": false}

期待されるレスポンス形式：

{
  "terminology": "snomedct",
  "fhir_base_url": "http://localhost:8080/fhir",
  "summary": {"resourceType": "CapabilityStatement", "fhirVersion": "4.0.1"}
}

snomed_lookup：

{"code": "404684003", "terminology": "snomedct"}

期待されるレスポンス形式：

{
  "terminology": "snomedct",
  "code": "404684003",
  "found": true,
  "display": "Clinical finding",
  "system": "http://snomed.info/sct"
}

コードがエディションに存在しない場合、ツールはエラーではなく構造化された否定結果を返します：

{
  "terminology": "snomedct",
  "code": "99999999999",
  "found": false,
  "message": "Code '99999999999' was not found in this SNOMED CT edition/version. Verify the concept ID or search for the concept by term."
}

snowstorm_search_concepts（Snowstormのみ）：

{"terminology": "snomedct", "term": "myocardial infarction", "limit": 5}

期待されるレスポンス形式：

{
  "terminology": "snomedct",
  "term": "myocardial infarction",
  "branch": "MAIN",
  "returned": 5,
  "hits": [{"concept_id": "22298006", "pt": "Myocardial infarction"}]
}

使用例

これらの例は、AIアシスタントが自然言語の質問に応じてサーバーのツールをどのように使用するかを示しています。

例1 — 臨床概念の検索

ユーザー： 「SNOMED CTの概念22298006とは何ですか？」

アシスタントはsnomed_lookupを{"code": "22298006"}で呼び出し、その概念の優先語（「Myocardial infarction」）、SNOMED CTシステムURI、および関連するプロパティを受け取ります。アシスタントはその後、臨床的な意味を含め、その概念を平易な言葉でユーザーに説明できます。

例2 — 階層関係の確認

ユーザー： 「SNOMED CTにおいて、2型糖尿病は内分泌疾患の一種ですか？」

アシスタントはsnomed_subsumesを{"code_a": "362969004", "code_b": "44054006"}（それぞれ内分泌疾患と2型糖尿病）で呼び出します。レスポンスはcode_aがcode_bを包含するかどうかを示し、IS-A関係を確認または否定します。

例3 — 臨床用語による概念の検索

ユーザー： 「『心房細動』に関連するSNOMED CTの概念を検索してください。」

アシスタントはsnomed_expandを{"filter": "atrial fibrillation", "count": 10}で呼び出し、用語集全体を検索します。レスポンスは一致する概念を、そのID、優先語、アクティブかどうかとともに返し、アシスタントが臨床的に関連する一致結果の簡潔なリストを提示できるようにします。

FHIR操作とマルチエディションSnowstorm

ネイティブなSnowstorm操作（検索、概念詳細）では、用語集のブランチパスが自動的に使用され、正しいエディションが選択されます。

FHIR操作（$lookup、$validate-code、$subsumes）では、用語集は正しいバックエンドサーバーにルーティングされます。マルチエディションのSnowstormインスタンスでは、正確なエディション指定のためにFHIRのversionパラメータを追加で指定する必要がある場合があります。FHIRのエディション選択はブランチパスではなくsystem/versionパラメータによって制御されるためです。

追加のバックエンド機能に関する注意事項とv0.1のスコープ境界はdocs/v0.1-capability-matrix.mdに文書化されています。リリースのタグ付け／スモークテスト手順はdocs/release-v0.1-checklist.mdにあります。

パフォーマンスガード

バックエンドへのHTTP呼び出しを行うすべてのツールは、Snowstormインスタンスを過負荷から保護するための共通のガードセットを共有します。これらは、呼び出されるツールに関係なく適用されます — server_health、server_capabilities、fhir_metadata、snomed_expand、snomed_lookup、snomed_validate_code、snomed_subsumes、すべての階層ツール、およびすべてのsnowstorm_*ネイティブツールです。

常にアクティブなガード：

プロセスごとのみ。 ガードはインメモリ状態を使用します。ロードバランサーの背後で複数のサーバープロセスを実行する場合、各プロセスは独自の独立した制限を適用します。プロセス間で共有される制限には、Redisバックエンドの実装が必要です。

セッションごとのレート制限（stdioのみ）

MCP 2026-07-28でプロトコルレベルのセッションが削除されました。 Streamable HTTPでは各リクエストが独立しているため、per_session_rate_limit_callsは安定したキーを持てず、トリガーされることはありません — 各リクエストは新しく空のウィンドウを取得します。設定した場合、サーバーは起動時に警告をログに記録します。stdioでは引き続き機能します。stdioでは1つのプロセスが正確に1つのクライアントにサービスを提供します。HTTPデプロイメントでは、代わりにリバースプロキシでクライアントごとの制限を行ってください（Nginx limit_req、Caddy rate_limit、Cloudflareなど）。これは、プロトコルがもはや伝達しないネットワークIDをキーとして使用します。

グローバルレート制限はすべての呼び出し元で共有され、影響を受けません — これはバックエンド全体の負荷を制限するコントロールであり続けます：

guards:
  rate_limit_calls: 30            # global ceiling across all callers
  rate_limit_window_seconds: 60
  per_session_rate_limit_calls: 8 # stdio only; a no-op over HTTP

per_session_rate_limit_callsが設定されている場合、各セッションは同じrate_limit_window_secondsを使用して独自の独立したローリングウィンドウを取得します。セッションはオブジェクトIDによって追跡され、基になるセッションオブジェクトがガベージコレクトされると自動的に破棄されます。

ガードなしツール

Snowstormバックエンドを呼び出さないインメモリツールは、意図的にガードなしのままになっています：list_terminologies。

Snowstormネイティブ検索の制約（重要）

MCPツールsnowstorm_search_conceptsは、Snowstormのネイティブな説明検索エンドポイント（GET /browser/{branch}/descriptions）を呼び出します。このエンドポイントは、非常に短いクエリ（例：AD、B2）をHTTP 400で拒否する場合があります。

実用的なガイダンス：

• 検索可能な文字（英字／数字）を少なくとも3文字使用します。

• 短い頭字語の場合は、コンテキストを含めます（例：ADの代わりに長いフレーズを使用）。

MCPサーバーはこれを早期に検証します：短すぎる用語は、Snowstormを呼び出さずに、ヒット数ゼロと制約を説明するnoticeフィールドを含む成功レスポンスを返します。想定される否定的な結果（短すぎる用語、または存在しないsnomed_lookupコード）はツールエラーではなく構造化データとして返されるため、MCPエラーメトリクスは実際の障害のみを反映します。

プライバシーポリシー

このサーバーは、MCPクライアントと設定されたSNOMED CTバックエンド（SnowstormまたはSnowstorm Lite）の間のステートレスなプロキシとして機能します。個人データを収集、保存、処理することはなく、設定されたバックエンド以外の第三者にデータを送信することもありません。すべてのクエリコンテンツはバックエンドに転送され、レスポンスが配信された後に破棄されます。セッションごとのレート制限が有効な場合、サーバーはレート適用のためだけにセッションごとのインメモリ呼び出しタイムスタンプを保持します。この状態にはPIIは含まれず、セッションが終了すると自動的に破棄されます。

レスポンスにはSNOMED CT用語集コンテンツが含まれます。このサーバーを通じたそのコンテンツへのアクセスは、SNOMED CTブラウザライセンス契約（下記のライセンスを参照）に準拠します。ホステッドサービスとしてデプロイされた場合、標準的なWebサーバーアクセスログ（IPアドレス、タイムスタンプ、リクエストパス）が運用目的でホスティングインフラストラクチャによって保持される場合があります。

完全なプライバシーポリシーについては、PRIVACY.mdを参照してください。

サポート

• 問題とバグ報告： GitHub Issues

• SNOMED CTのライセンスとコンテンツ： SNOMED International

• 一般的なお問い合わせ： info@snomed.org

ライセンス

サーバーソフトウェアはApache 2.0の下でライセンスされています。

このサーバーが返すSNOMED CTコンテンツは、そのライセンスの対象外です。このサーバーを通じたSNOMED CTへのアクセスは、SNOMED CTブラウザライセンス契約に準拠します。これは、公開されているSNOMED CTブラウザが提供されるのと同じ基準です。要約すると、SNOMED Internationalアフィリエイトライセンスを保有していないエンドユーザーは、このサーバーを使用して用語集を調査および評価できますが、以下を行うことはできません：

• SNOMED CT識別子をレコードシステム、データベース、または文書にコピーすること（「データ作成システム」または「データ分析システム」としての使用）；

• SNOMED CTコンテンツを翻訳または変更すること；または

• SNOMED CTコンテンツを再配布または共有すること。

このサーバーを自分でホストする場合、SNOMED CTを製品やサービスに統合する場合、または調査・評価以外の目的でSNOMED CTを使用する場合は、完全なSNOMED CTライセンスを取得する必要があります — Get SNOMED CTを参照してください。SNOMED Internationalアフィリエイトは、アフィリエイトライセンスの条件内でこのサーバーを使用できます。SNOMED CTは© SNOMED Internationalです。「SNOMED」および「SNOMED CT」は登録商標です。