npi-providers-mcp-server

---

概要

NPI Registry に登録された米国の医療プロバイダーディレクトリです。平易な言葉で名前、所在地、専門分野から医師や組織を検索し、任意の NPI をプロバイダーの記録に変換して、NUCC の専門分野分類を参照できます。

ツール

ツール	説明
npi_search_providers	名前、組織、所在地、プロバイダーの種類、専門分野を指定して NPPES レジストリを検索します。平易な言葉で指定された専門分野は、検索前に同梱の NUCC 分類を使って解決されます。
npi_get_provider	最大 10 件の NPI について、NPPES の専門診療記録（分類、診療所住所、資格、識別子、エンドポイント、ステータス）を取得します。個人プロバイダーについては、LOCATION の住所行のみを保持します。
npi_lookup_taxonomy	NUCC の医療プロバイダー分類を、オフラインで解決、取得、または参照します。

リソース

リソース	説明
npi://provider/{npi}	NPI に基づく、デコード済みの単一プロバイダー記録です。npi_get_provider に対応するリソースです。
npi://taxonomy/{code}	コードに基づく、単一の NUCC 分類エントリーです。npi_lookup_taxonomy の get モードに対応するリソースです。

すべてのリソースデータはツールからも利用できます。リソースは、リソース対応クライアント向けの便利な対応機能です。

同梱の npi-providers-guide スキルは skill://npi-providers-guide/SKILL.md で利用できます。専門分野ごとのグループ、プロバイダーの識別、網羅的なディレクトリ検索の限界について説明しています。

機能リファレンス

npi_search_providers _ツール

• 入力：name_search、または first_name / last_name（個人）、organization_name（組織）、provider_type、city / state / postal_code（診療所住所のみ）、NUCC 分類を使って解決する平易な表現の specialty、または完全一致する taxonomy_description（両方は指定できません）。少なくとも 1 つの条件が必要です。州のみの指定は拒否され、個人と組織の条件を混在させることはできません。末尾の * の前には 2 文字以上が必要です。postal_code には 5 桁または 9 桁の数字、あるいは末尾に * を付けた 2～9 桁の数字を指定します。正の値を指定する limit（上限 200、デフォルト 10）、skip は 0～1000 です。省略可能な use_first_name_alias は、上流の名のバリエーションを制御します。省略した場合、ワイルドカードなしの名ではデフォルトで true になります。ワイルドカード検索または名を指定しない検索でこのオプションを指定すると、適用対象外として報告されます
• 出力：コンパクトな行（npi、名前、主分類、主な診療所の city / state / postalCode、status）。matchedLocation / matchedOtherName には、行が一致した診療所の所在地または別名が示され、resolvedTaxonomies / appliedTaxonomyDescription には専門分野の解決結果が反映されます。appliedFirstNameAlias には、ワイルドカードなしの名に対してのみ、有効なブール値が示されます。正確な総件数は報告されません。ページが満杯の場合は nextPage が示され、終端ウィンドウ（skip 1000、limit 200）では検索を続けるための continuationPostalCodes が返されます
• 型付きエラー理由：no_search_criteria、conflicting_specialty、mixed_provider_criteria、unresolved_specialty、invalid_search_field

---

npi_get_provider _ツール

• npis を受け取ります。単一の NPI、またはそれぞれ正確に 10 桁の数字である最大 100 件の生のエントリーを指定できます。重複を除去し、すべてのチェックデジットを検証した後、最初の 10 件の有効な固有 NPI を検索します。省略可能な unprocessed には、残りの有効な NPI が順番どおりに一覧表示されます。NPI_CLAMP_LIMITS=false の場合、生の配列の最大件数は 10 です
• バッチを found（デコードされたレコード：ライセンス付き分類、診療所住所、資格、識別子、FHIR／Direct エンドポイント、ステータス。個人プロバイダーについては LOCATION の住所行のみで、郵送先住所は返されません）、notFound（不在を確認済み）、errored（上流の障害。再試行してください）、invalid（チェックデジットの検証に失敗し、検索されていません）に分類します
• 型付きエラー理由：invalid_npi_format（すべての NPI がチェックデジットの検証に失敗）、none_found（検索したすべての NPI が不在と確認された場合）。上流の障害が発生した場合は、代わりにその基となるエラーが表面化します。エラーメッセージと構造化エラーデータには、無効な NPI と未処理の残りのすべてが保持されます

---

npi_lookup_taxonomy _ツール

• モード：resolve（query → 一致する有効なコード）、get（完全一致する code → NUCC の notes を含む完全なエントリー）、browse（グルーピング → 分類 → 専門分野の順に参照。grouping と NUCC の section で絞り込み可能）。Section は分類カテゴリを示すもので、プロバイダーの NPI エンティティタイプではありません。後者には検索の provider_type を使用してください。resolve / browse では、正の値を指定する limit（上限 50、デフォルト 20）と skip（0～1000）を指定でき、truncated が開示されます。誤ったモードの引数は、デフォルトが適用される前に拒否されます
• すべてのエントリーには status（active / inactive）が含まれ、非アクティブなコードには replacedBy が含まれます。resolve は非アクティブなコードを除外しますが、get と browse はそれらを返します。解決されたエントリーの specialization（ない場合は classification）は、npi_search_providers.taxonomy_description が受け付ける正確な値です
• 定義と注記には、NUCC の HTML マークアップに代わり、読みやすい改行とリスト項目が含まれます。リテラルのマーカーとソーステキストはそのまま保持されます
• 型付きエラー理由：no_match、missing_argument、wrong_mode_argument

---

npi://provider/{npi} _リソース

• 1 つの NPI について、npi_get_provider と同じデコード済みレコードを application/json で返します。個人プロバイダーの場合、LOCATION の住所行のみを保持します
• npi は正しい形式の 10 桁の NPI である必要があります。NPI チェックディジットの検証に失敗した場合は invalid_npi_format（レジストリへのリクエストは行いません）、レジストリに該当レコードがない場合は no_record（登録解除済み、または一度も登録されていない場合）を返します

---

npi://taxonomy/{code} _リソース

• npi_lookup_taxonomy の get モードと同じエントリーを application/json で返します（NUCC の notes、status、replacedBy を含みます。非アクティブなコードも参照できます）。24 時間、公開キャッシュされます
• code は ^\d{3}[A-Z0-9]{6}X$ に一致する必要があります。該当するコードのエントリーがない場合は no_match を返します

機能

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

NPI／NPPES 固有の機能：

• キー不要 — API キーやアカウントなしで、一般公開されている CMS NPPES NPI Registry API（v2.1）を利用します
• NUCC 分類を同梱 — 883 コードの Healthcare Provider Taxonomy（v26.1）をイメージに同梱し、起動時にインメモリーインデックスへ読み込みます。そのため、専門分野の解決やコード検索を、2 つ目の上流サービスを使わずに完全オフラインで実行できます
• 専門分野の解決では、「心臓の医師」のような曖昧な語句を、レジストリのフィルターで使用される正確な分類の説明に変換し、エージェントが確認できるよう一致した内容を返します
• 検証失敗時に Errors[] を含む本文とともに HTTP 200 を返すレジストリの特性を検出し、型付きの回復可能なエラー理由に変換します

エージェントに適した出力：

• 検索の出典情報 — 解決された分類と、レジストリに送信された正確な taxonomy_description を返すため、エージェントは実際に検索された内容を確認し、別のコードで再実行できます
• 正確なページネーション — 返される件数はページサイズとして明示し、存在しない総件数を捏造しません。ページが満杯の場合は正確な次ページを示し、広範なクエリが到達可能な 1200 件の上限に達した場合は、検索を続けられる郵便番号のプレフィックスを返します
• 部分的な失敗を適切に処理 — npi_get_provider はバッチ全体を失敗させず、NPI ごとに found／notFound／errored／invalid の行を返します

はじめに

インストールせずに、ホストされたインスタンスに接続します：

claude mcp add --transport http npi-providers-mcp-server https://npi-providers.caseyjhand.com/mcp

または、ローカルで実行します：

claude mcp add npi-providers-mcp-server -- npx -y @cyanheads/npi-providers-mcp-server

その他のクライアントでは、MCP 設定ファイルに以下を追加します：

{
  "mcpServers": {
    "npi-providers-mcp-server": {
      "command": "npx",
      "args": ["-y", "@cyanheads/npi-providers-mcp-server"]
    }
  }
}

API キーは不要です。Docker またはソースからのビルドについては、サーバーの実行を参照してください。

設定

必須の変数はありません。サーバーはキー不要の NPPES レジストリをそのまま利用して動作します。以下の変数はすべて任意の上書き設定です。

変数	説明	デフォルト
NPPES_API_BASE_URL	NPPES NPI レジストリ API のベース URL です。プライベートミラーやテスト用に上書きできます。	https://npiregistry.cms.hhs.gov/api
NPPES_TIMEOUT_MS	NPPES 呼び出しごとの HTTP タイムアウト（ミリ秒）です。	15000
NPI_CLAMP_LIMITS	検索上限を 200、分類上限を 50 に制限します。また、10 件の異なる有効な NPI を検索する際に、未加工の NPI を 100 件受け付けます。False にすると、スキーマの上限である検索 200、分類 50、未加工の NPI 10 件に戻ります。実際に上限が適用されるたびに、通知、ログ、カウンターイベントが記録されます。	true
MCP_TRANSPORT_TYPE	トランスポート：stdio または http です。	stdio
MCP_HTTP_PORT	HTTP サーバーのポートです。	3010
MCP_AUTH_MODE	認証モード：none、jwt、または oauth です。	none
MCP_SESSION_MODE	HTTP セッションの処理方式：stateless、stateful、または auto です。このサーバーでは stateless が固定されます。スキーマのデフォルトである auto は stateful に解決されます。	stateless
MCP_LOG_LEVEL	ログレベル（RFC 5424）です。	info
LOG_TOOL_FAILURE_PAYLOADS	失敗したツール呼び出しごとに、引数と結果をログに記録します。キー名に基づいて機密情報をマスキングし、LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES（デフォルトは 16384）で長さを制限します。自由形式の値に含まれる秘密情報はマスキングされません。	false
STORAGE_PROVIDER_TYPE	ストレージバックエンドです。	in-memory
OTEL_ENABLED	OpenTelemetry インストルメンテーション（スパン、メトリクス、完了ログ）を有効にします。	false

任意の上書き設定の一覧については、.env.example を参照してください。

サーバーの実行

ローカル開発

Bun v1.4.0 以上（または Node.js v24 以上）が必要です。NPPES レジストリはキー不要で、NUCC 分類はバンドルされています。

• クローンしてインストール：

  git clone https://github.com/cyanheads/npi-providers-mcp-server.git
  cd npi-providers-mcp-server && bun install
  cp .env.example .env   # optional NPPES base URL and timeout overrides
  

• ビルドして実行：

  # 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 npi-providers-mcp-server .
docker run --rm -e MCP_TRANSPORT_TYPE=http -p 3010:3010 npi-providers-mcp-server

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

プロジェクト構成

ディレクトリ	用途
src/index.ts	createApp() のエントリーポイントです。ツールとリソースを登録し、サービスを初期化します。
src/config	サーバー固有の環境変数を解析し、Zod で検証します。
src/mcp-server/tools	ツール定義（*.tool.ts）です。
src/mcp-server/resources	リソース定義（*.resource.ts）です。
src/services/nppes	NPPES NPI レジストリ API クライアントです。クエリの構築、200 応答時の Errors[] 検出、正規化を行います。
src/services/taxonomy	バンドルされた NUCC 分類サービスです。resolve／get／browse 用のインメモリーインデックスを提供します。
skills/	公開されるエージェントガイドです。パッケージに同梱され、MCP 経由で提供されます。
tests/	src/ に対応するユニットテストと統合テストです。

開発ガイド

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

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールロジック内で try/catch を使用しないでください。
• リクエスト単位のログには ctx.log、テナント単位のストレージには ctx.state を使用します。
• 新しいツールとリソースは createApp() の配列に登録します。
• 外部 API 呼び出しは、未加工データを検証し、ドメイン型に正規化してから、出力スキーマに従って返します。不足しているフィールドを捏造しないでください。

データの帰属

CMS NPPES NPI Registry のプロバイダーデータ（パブリックドメイン）。同梱されている専門分野コードは、NUCC Health Care Provider Taxonomy（National Uniform Claim Committee（NUCC）に代わり American Medical Association が著作権を保有）であり、NUCC の許可に基づき、書式以外は変更せず再配布しています。NOTICE をご覧ください。

貢献

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

bun run devcheck
bun run test

ライセンス

Apache-2.0 — 詳細は LICENSE をご覧ください。