io.github.cyanheads/npi-providers-mcp-server

Official3 toolsLive

by cyanheads · TypeScript

Search NPPES providers and resolve NUCC specialty codes via MCP over STDIO or Streamable HTTP.

Search NPPES providers and resolve NUCC specialty codes via an MCP server. The server exposes MCP tools over STDIO or Streamable HTTP and supports a provider-directory workflow for NPI/NPPES and NUCC specialty code lookups.

🛠️ Key Features

Search NPPES providers
Resolve NUCC specialty codes
MCP access over STDIO or Streamable HTTP
Built as an MCP server (3 tools)

🚀 Use Cases

Provider directory queries by NPI/NPPES data
Translating provider specialties using NUCC specialty codes
Integrating healthcare provider lookup into AI agents

⚡ Developer Benefits

MCP-compatible interface for tool-based provider resolution
STDIO and Streamable HTTP connectivity options
Typed, TypeScript-oriented ecosystem (topics include TypeScript, AI agents)

⚠️ Limitations

Only described capability is NPPES provider search and NUCC specialty code resolution

Topics

cmscyanheadshealth-techhealthcaremcpmcp-servermodel-context-protocolnpinppesnuccprovider-directorytypescriptai-agentsproviders

Captured live from the server via tools/list.

npi_search_providers

Search the NPPES NPI registry for individual practitioners and healthcare organizations by name, organization name, location, provider type, and specialty. Plain-language specialty terms (e.g. "cardiologist", "pediatric cardiologist") resolve through the bundled NUCC taxonomy; the top match's specialization or classification becomes taxonomy_description, and all resolved candidates are returned in metadata. Location belongs in the dedicated city/state/postal_code inputs, not inside specialty. Each provider row includes the NPI, name, primary specialty, city/state/ZIP, type, and active/deactivated status; the NPI is the input for npi_get_provider when the full record is needed. At least one search criterion is required, and the registry rejects state-only searches. When city/state/postal_code are given, only practice addresses are searched, never mailing addresses: a provider is returned only when its primary practice location or one of its other practice locations matches all of them. A provider kept on another practice location names it in matchedLocation. Name searches also match former and other names, sorted by current name; such a row names the matching name in matchedOtherName. The registry never reports a true match total, and one search reaches only its first 1200 matches: a full page names the next in nextPage, and the terminal window (skip 1000, limit 200) returns continuationPostalCodes, postal_code prefixes that continue the search.

Parameters12

name_search	string	optional	One person's name. The first token becomes first_name and the last token becomes last_name; use first_name/last_name when middle names or multi-part surnames matter.
first_name	string	optional	Individual first name. Trailing wildcard "*" allowed with at least 2 leading characters.
last_name	string	optional	Individual last name. Trailing wildcard "*" allowed with at least 2 leading characters.
organization_name	string	optional	Organization name (implies provider_type organization; cannot be combined with first_name, last_name, or name_search). Trailing wildcard "*" allowed with at least 2 leading characters.
provider_type	string	optional	Restrict to individuals (NPI-1) or organizations (NPI-2). Omit to search both; when set, it must match the name fields ("individual" for first_name/last_name/name_search, "organization" for organization_name).
specialty	string	optional	Plain-language specialty (e.g. "pediatric cardiologist"), resolved through the bundled NUCC taxonomy to exact descriptions before searching. Codes NUCC marks inactive are never resolved. The matched taxonomy is echoed in the result. Mutually exclusive with taxonomy_description.
taxonomy_description	string	optional	Exact NUCC taxonomy description for direct passthrough — use when the taxonomy description is already known. Mutually exclusive with specialty.
city	string	optional	Practice-location city, case-insensitive. A trailing "" after at least 2 characters matches every city starting with them (e.g. "SAN F").
state	any	optional	2-letter state code (e.g. "WA"). The registry rejects state-only searches, so another criterion is required. A blank value is treated as omitted.
postal_code	string	optional	Practice-location ZIP code: 5 digits (also matching the ZIP+4 codes that extend it), 9 digits, or a 2–9 digit prefix with one trailing "" (e.g. "98", "981*"). A ZIP+4 prefix (6+ digits) never matches a practice address recorded with only a 5-digit ZIP.
limit	integer	optional	Maximum providers to return (1–200; the registry caps at 200).
skip	integer	optional	Results to skip for pagination (0–1000). A full page names the next in nextPage.

Raw schema

{
  "type": "object",
  "properties": {
    "name_search": {
      "description": "One person's name. The first token becomes first_name and the last token becomes last_name; use first_name/last_name when middle names or multi-part surnames matter.",
      "type": "string"
    },
    "first_name": {
      "description": "Individual first name. Trailing wildcard \"*\" allowed with at least 2 leading characters.",
      "type": "string"
    },
    "last_name": {
      "description": "Individual last name. Trailing wildcard \"*\" allowed with at least 2 leading characters.",
      "type": "string"
    },
    "organization_name": {
      "description": "Organization name (implies provider_type organization; cannot be combined with first_name, last_name, or name_search). Trailing wildcard \"*\" allowed with at least 2 leading characters.",
      "type": "string"
    },
    "provider_type": {
      "description": "Restrict to individuals (NPI-1) or organizations (NPI-2). Omit to search both; when set, it must match the name fields (\"individual\" for first_name/last_name/name_search, \"organization\" for organization_name).",
      "type": "string",
      "enum": [
        "individual",
        "organization"
      ]
    },
    "specialty": {
      "description": "Plain-language specialty (e.g. \"pediatric cardiologist\"), resolved through the bundled NUCC taxonomy to exact descriptions before searching. Codes NUCC marks inactive are never resolved. The matched taxonomy is echoed in the result. Mutually exclusive with taxonomy_description.",
      "type": "string"
    },
    "taxonomy_description": {
      "description": "Exact NUCC taxonomy description for direct passthrough — use when the taxonomy description is already known. Mutually exclusive with specialty.",
      "type": "string"
    },
    "city": {
      "description": "Practice-location city, case-insensitive. A trailing \"*\" after at least 2 characters matches every city starting with them (e.g. \"SAN F*\").",
      "type": "string",
      "pattern": "^[^*]*$|^[^*]{2,}\\*$"
    },
    "state": {
      "description": "2-letter state code (e.g. \"WA\"). The registry rejects state-only searches, so another criterion is required. A blank value is treated as omitted.",
      "anyOf": [
        {
          "type": "string",
          "const": ""
        },
        {
          "type": "string",
          "pattern": "^[A-Z]{2}$",
          "description": "2-letter state code (e.g. \"WA\")."
        }
      ]
    },
    "postal_code": {
      "description": "Practice-location ZIP code: 5 digits (also matching the ZIP+4 codes that extend it), 9 digits, or a 2–9 digit prefix with one trailing \"*\" (e.g. \"98*\", \"981*\"). A ZIP+4 prefix (6+ digits) never matches a practice address recorded with only a 5-digit ZIP.",
      "type": "string",
      "pattern": "^[^*]*$|^\\d{2,9}\\*$"
    },
    "limit": {
      "default": 10,
      "description": "Maximum providers to return (1–200; the registry caps at 200).",
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    },
    "skip": {
      "default": 0,
      "description": "Results to skip for pagination (0–1000). A full page names the next in nextPage.",
      "type": "integer",
      "minimum": 0,
      "maximum": 1000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

npi_get_provider

Fetch the NPPES record for one or more NPI numbers (up to 10 per call). Decodes an NPI from a claim, prescription, or another health data source into the provider's professional-practice profile: every taxonomy with its primary flag, license number and state; practice addresses with phone and fax (only LOCATION rows are kept for individual providers, so their mailing address is withheld; organizations also carry their mailing address); credential, sex, sole-proprietor flag; enumeration and last-updated dates; active/deactivated status; secondary identifiers (Medicaid, etc.); and FHIR/Direct endpoints. Each NPI must be 10 digits with a valid check digit (its last digit); an NPI failing the check digit lands in invalid and is never looked up. Reports partial success: valid NPIs with no registry record (deactivated or never enumerated) land in notFound, while NPIs whose lookup hit an upstream error (registry unavailable, timeout) land in errored — kept distinct from confirmed misses — rather than failing the whole call.

Parameters1

npis

any

required

A single 10-digit NPI, or an array of up to 10. Each must be exactly 10 digits; each is also checked against its NPI check digit before any API call, and one that fails is reported in invalid.

Raw schema

{
  "type": "object",
  "properties": {
    "npis": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^\\d{10}$",
          "description": "A 10-digit National Provider Identifier whose last digit is its check digit (Luhn over the number prefixed with 80840)."
        },
        {
          "minItems": 1,
          "maxItems": 10,
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^\\d{10}$",
            "description": "A 10-digit National Provider Identifier whose last digit is its check digit (Luhn over the number prefixed with 80840)."
          },
          "description": "An array of up to 10 ten-digit NPIs."
        }
      ],
      "description": "A single 10-digit NPI, or an array of up to 10. Each must be exactly 10 digits; each is also checked against its NPI check digit before any API call, and one that fails is reported in invalid."
    }
  },
  "required": [
    "npis"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

npi_lookup_taxonomy

Resolve and browse the NUCC Healthcare Provider Taxonomy — the specialty code set NPPES uses — fully offline (bundled). Mode `resolve` turns a plain-language specialty (e.g. "cardiologist", "heart doctor") into matching active taxonomy entries, excluding codes NUCC marks inactive; mode `get` returns the full entry for an exact code, including NUCC's Notes; mode `browse` walks the hierarchy (grouping → classification → specialization), optionally filtered by grouping and by NPI section (Individual/NPI-1 vs Non-Individual/NPI-2). Every entry carries its status, and an inactive code names its replacement when NUCC gives one; `get` and `browse` still return inactive codes. A resolved entry's specialization, or its classification when specialization is absent, maps directly to npi_search_providers.taxonomy_description.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "mode": {
          "type": "string",
          "const": "resolve",
          "description": "Resolve a plain-language specialty to taxonomy codes."
        },
        "query": {
          "type": "string",
          "minLength": 1,
          "description": "The plain-language specialty term to resolve, e.g. \"pediatric cardiologist\"."
        },
        "limit": {
          "default": 20,
          "description": "Maximum matching entries to return (1–50).",
          "type": "integer",
          "minimum": 1,
          "maximum": 50
        },
        "skip": {
          "default": 0,
          "description": "Entries to skip before the page (0–1000). Keep the same query and limit, then raise skip by limit each call.",
          "type": "integer",
          "minimum": 0,
          "maximum": 1000
        }
      },
      "required": [
        "mode",
        "query"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "mode": {
          "type": "string",
          "const": "get",
          "description": "Fetch one exact taxonomy entry by code."
        },
        "code": {
          "type": "string",
          "minLength": 1,
          "description": "The exact NUCC taxonomy code, e.g. \"207RC0000X\"."
        }
      },
      "required": [
        "mode",
        "code"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "mode": {
          "type": "string",
          "const": "browse",
          "description": "Browse the taxonomy hierarchy."
        },
        "grouping": {
          "description": "Filter to a top-level grouping by case-insensitive substring, e.g. \"physicians\".",
          "type": "string"
        },
        "section": {
          "description": "Filter by NPI section: Individual (NPI-1) or Non-Individual (NPI-2).",
          "type": "string",
          "enum": [
            "Individual",
            "Non-Individual"
          ]
        },
        "limit": {
          "default": 20,
          "description": "Maximum entries to return (1–50).",
          "type": "integer",
          "minimum": 1,
          "maximum": 50
        },
        "skip": {
          "default": 0,
          "description": "Entries to skip before the page (0–1000). Keep the same filters and limit, then raise skip by limit each call.",
          "type": "integer",
          "minimum": 0,
          "maximum": 1000
        }
      },
      "required": [
        "mode"
      ],
      "additionalProperties": false
    }
  ]
}

README.md17 KBView on GitHub

@cyanheads/npi-providers-mcp-server

Search NPPES providers and resolve NUCC specialty codes via MCP over STDIO or Streamable HTTP.

3 Tools • 2 Resources

Version MCP SDK TypeScript

Public Hosted Server: https://npi-providers.caseyjhand.com/mcp

Overview

US healthcare provider directory over the NPPES NPI Registry, with plain-language specialty terms resolved offline against a bundled NUCC taxonomy. Search providers by name, organization, location, and specialty; decode NPIs into professional-practice provider records; and resolve or browse the NUCC taxonomy directly. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

Tools

Tool	Description
`npi_search_providers`	Search the NPPES registry by name, organization, location, provider type, and specialty. Plain-language specialties resolve through the bundled NUCC taxonomy before searching.
`npi_get_provider`	Fetch the NPPES professional-practice record for up to 10 NPIs — taxonomies, practice addresses, credentials, identifiers, endpoints, and status. Only LOCATION address rows are kept for individual providers.
`npi_lookup_taxonomy`	Resolve, fetch, or browse the NUCC Healthcare Provider Taxonomy — fully offline.

Resources

Resource	Description
`npi://provider/{npi}`	A single provider's decoded record by NPI — the resource twin of `npi_get_provider`.
`npi://taxonomy/{code}`	A single NUCC taxonomy entry by code — the resource twin of `npi_lookup_taxonomy` mode `get`.

All resource data is also reachable via tools; the resources are convenience twins for resource-capable clients.

Capability reference

`npi_search_providers` _tool

Search by name_search shortcut, explicit first_name / last_name, organization_name, city / state / postal_code, and provider_type (individual / organization); at least one criterion is required and the registry rejects state-only searches. Person names search individuals and organization_name searches organizations, so mixing the two sides (directly or through provider_type) fails before any registry request
Plain-language specialty resolves through the bundled NUCC taxonomy to the registry's exact description before searching, echoed back via resolvedTaxonomies / appliedTaxonomyDescription; inactive NUCC codes are never resolved. taxonomy_description is an escape hatch for an already-known exact description (mutually exclusive with specialty)
Trailing-wildcard (*) matching on names, organization, and city requires at least 2 leading characters; postal_code takes 5 or 9 digits, or a 2–9 digit prefix ending in * (98*, 981*)
Name searches also match former and other names, and the registry sorts by current name; a row matched through one names it in matchedOtherName (an exact first_name alone never marks a row, since the registry also matches first-name variants)
Each row's city / state / postalCode is the primary practice location. A location search matches practice addresses only, never mailing addresses: a row is returned only when the primary practice location or another practice location matches every requested location field (any other row the registry returns is filtered out, with a notice counting it), and a row kept on another practice location names it in matchedLocation
limit 1–200 (default 10), skip 0–1000; the registry never reports a true match total, and the response discloses page-size-not-total via truncated / notice. A full page names the next page in nextPage; one search reaches only its first 1200 matches, so the terminal window (skip 1000, limit 200) instead returns continuationPostalCodes — postal_code prefixes to re-run the same search with, deduplicating by NPI. That split cannot go below a 5-digit ZIP or reach practice addresses outside the US, and the notice says so
Typed error reasons: no_search_criteria, conflicting_specialty, mixed_provider_criteria, unresolved_specialty, invalid_search_field

`npi_get_provider` _tool

Accepts a single NPI or up to 10; each must be exactly 10 digits, and each is checked against its NPI check digit before any API call
Returns every taxonomy (with primary flag, license number and state), practice addresses with phone and fax, credential, sex, sole-proprietor flag, enumeration and last-updated dates, secondary identifiers, and FHIR/Direct endpoints (with their descriptions and routing address)
Only LOCATION (practice) address rows are kept for individual providers, so their mailing address — often a home address — is withheld; organizations keep both LOCATION and MAILING rows
Four-way partition: found (resolved records), notFound (confirmed absence — deactivated or never enumerated), errored (upstream failure, distinct from absence — retry these), invalid (failed the NPI check digit — never looked up)
Throws invalid_npi_format when every requested NPI fails the check digit, and none_found only when every NPI looked up is a confirmed absence; an upstream failure on any NPI surfaces as that underlying error instead

`npi_lookup_taxonomy` _tool

Three modes: resolve (plain-language term → matching codes/descriptions), get (exact code → full entry, including NUCC's notes), browse (walk grouping → classification → specialization, filterable by grouping and NPI section)
Every entry carries status (active / inactive) and, for an inactive code, the replacedBy code NUCC names; resolve never returns inactive codes, while get and browse still do. A query that matches only inactive codes fails with no_match naming them and their replacements
Credential abbreviations resolve, dotted or not (rn, R.N., np, pa, crna, lpn, lvn, emt, er). A query made only of generic words, singular or plural (physician, doctors, M.D., specialist, providers), names no specialty, so it fails with no_match and a hint to browse, rather than matching an unrelated word
resolve / browse cap results at limit (≤50, default 20) and disclose truncated; page past the cap with skip (0–1000, raised by limit each call)
A resolved entry's specialization (or classification when specialization is absent) is the exact value npi_search_providers.taxonomy_description accepts
Typed error reasons: no_match, missing_argument

`npi://provider/{npi}` _resource

Returns the same decoded record as npi_get_provider, for one NPI, as application/json — only LOCATION address rows are kept for individual providers
npi must be a well-formed 10-digit NPI; invalid_npi_format when it fails the NPI check digit (no registry request), no_record when the registry has none (deactivated or never enumerated)

`npi://taxonomy/{code}` _resource

Returns the same entry as npi_lookup_taxonomy mode get (NUCC notes, status, and replacedBy included; inactive codes stay readable), as application/json; cached publicly for 24 hours
code must match ^\d{3}[A-Z0-9]{6}X$; no_match when no entry exists for the code

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

NPI/NPPES-specific:

Keyless — runs against the public CMS NPPES NPI Registry API (v2.1) with no API key or account
Bundled NUCC taxonomy — the 883-code Healthcare Provider Taxonomy (v26.1) ships in the image and loads into an in-memory index at startup, so specialty resolution and code lookups work fully offline with no second upstream
Specialty resolution turns a vague term ("heart doctor") into the precise taxonomy description the registry filters on, and echoes the match back for the agent to verify
Detects the registry's quirk of returning HTTP 200 with an Errors[] body on validation failure and maps it to typed, recoverable error reasons

Agent-friendly output:

Provenance on search — the resolved taxonomy and the exact taxonomy_description sent to the registry are echoed back, so agents can see what was actually searched and re-run with a different code
Honest pagination — the returned count is disclosed as the page size, never a fabricated grand total; a full page names the exact next page, and a broad query that hits the 1200-match reachable ceiling gets the postal-code prefixes that continue it
Graceful partial failure — npi_get_provider returns per-NPI found / notFound / errored / invalid rows instead of failing the whole batch

Getting started

Public Hosted Instance

A public instance is available at https://npi-providers.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP, with this client config:

json

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

Self-Hosted / Local

Add the following to your MCP client configuration file. No API key is required — the upstream NPPES registry is keyless.

json

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

Or with npx (no Bun required):

json

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

Or with Docker:

json

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

For Streamable HTTP, set the transport and start the server:

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

Prerequisites

Bun v1.4.0 or higher (or Node.js v24+).
No API key — the NPPES NPI Registry API is public and keyless. The NUCC taxonomy is bundled, so there is no second data source to provision.

Installation

Clone the repository:

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

Navigate into the directory:

cd npi-providers-mcp-server

Install dependencies:

bun install

Configure environment (optional):

cp .env.example .env
# edit .env only if you need to override the NPPES base URL or timeout

Configuration

No required variables — the server runs out of the box against the keyless NPPES registry. All variables below are optional overrides.

Variable	Description	Default
`NPPES_API_BASE_URL`	NPPES NPI Registry API base URL. Override for a private mirror or testing.	`https://npiregistry.cms.hhs.gov/api`
`NPPES_TIMEOUT_MS`	Per-request HTTP timeout for NPPES calls, in milliseconds.	`15000`
`MCP_TRANSPORT_TYPE`	Transport: `stdio` or `http`.	`stdio`
`MCP_HTTP_PORT`	Port for the HTTP server.	`3010`
`MCP_AUTH_MODE`	Auth mode: `none`, `jwt`, or `oauth`.	`none`
`MCP_SESSION_MODE`	HTTP session handling: `stateless`, `stateful`, or `auto`. This server pins `stateless`; the schema default `auto` resolves to `stateful`.	`stateless`
`MCP_LOG_LEVEL`	Log level (RFC 5424).	`info`
`STORAGE_PROVIDER_TYPE`	Storage backend.	`in-memory`
`OTEL_ENABLED`	Enable OpenTelemetry instrumentation (spans, metrics, completion logs).	`false`

See .env.example for the full list of optional overrides.

Running the server

Local development

Build and run:

# One-time build
bun run rebuild

# Run the built server
bun run start:stdio
# or
bun run start:http

Run checks and tests:

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

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/npi-providers-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Directory	Purpose
`src/index.ts`	`createApp()` entry point — registers tools and resources, inits services.
`src/config`	Server-specific environment variable parsing and validation with Zod.
`src/mcp-server/tools`	Tool definitions (`*.tool.ts`).
`src/mcp-server/resources`	Resource definitions (`*.resource.ts`).
`src/services/nppes`	NPPES NPI Registry API client — query building, `Errors[]`-on-200 detection, normalization.
`src/services/taxonomy`	Bundled NUCC taxonomy service — in-memory index for resolve / get / browse.
`tests/`	Unit and integration tests mirroring `src/`.

Development guide

See CLAUDE.md/AGENTS.md for development guidelines and architectural rules. The short version:

Handlers throw, framework catches — no try/catch in tool logic
Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage
Register new tools and resources in the createApp() arrays
Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Data attribution

Provider data from the CMS NPPES NPI Registry (public domain). The bundled specialty codes are the NUCC Health Care Provider Taxonomy, © American Medical Association on behalf of the National Uniform Claim Committee (NUCC), redistributed unmodified beyond formatting under the NUCC permission. See NOTICE.

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.

Install

Tools (3)

npi_search_providersnpi_get_providernpi_lookup_taxonomy

Configuration

Environment variables

MCP_LOG_LEVELdefault info

Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').

NPPES_API_BASE_URLdefault https://npiregistry.cms.hhs.gov/api

NPPES NPI Registry API base URL. Override for a private mirror or testing.

NPPES_TIMEOUT_MSdefault 15000

Per-request HTTP timeout for NPPES calls, in milliseconds.

MCP_TRANSPORT_TYPEdefault http

Selects the HTTP transport.

MCP_HTTP_HOSTdefault 127.0.0.1

The hostname for the HTTP server.

MCP_HTTP_PORTdefault 3010

The port to run the HTTP server on.

MCP_HTTP_ENDPOINT_PATHdefault /mcp

The endpoint path for the MCP server.

MCP_AUTH_MODEdefault none

Authentication mode to use: 'none', 'jwt', or 'oauth'.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "npi-providers-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@cyanheads/npi-providers-mcp-server@0.4.1"
      ],
      "env": {
        "MCP_LOG_LEVEL": "info",
        "NPPES_API_BASE_URL": "https://npiregistry.cms.hhs.gov/api",
        "NPPES_TIMEOUT_MS": "15000"
      }
    }
  }
}

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

npi_search_providers

npi_get_provider

npi_lookup_taxonomy

@cyanheads/npi-providers-mcp-server

Overview

Tools

Resources

Capability reference

npi_search_providers tool

npi_get_provider tool

npi_lookup_taxonomy tool

npi://provider/{npi} resource

npi://taxonomy/{code} resource

Features

Getting started

Public Hosted Instance

Self-Hosted / Local

Prerequisites

Installation

Configuration

Running the server

Local development

Docker

Project structure

Development guide

Data attribution

Contributing

License

Install

Configuration

Related servers

`npi_search_providers` _tool

`npi_get_provider` _tool

`npi_lookup_taxonomy` _tool

`npi://provider/{npi}` _resource

`npi://taxonomy/{code}` _resource