npi-providers-mcp-server

<div align="center">
  <h1>@cyanheads/npi-providers-mcp-server</h1>
  <p><b>Search NPPES providers and resolve NUCC specialty codes via MCP over STDIO or Streamable HTTP.</b>
  <div>3 Tools • 2 Resources</div>
  </p>
</div>

<div align="center">

[![Version](https://img.shields.io/badge/Version-0.1.9-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/npi-providers-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/%40cyanheads%2Fnpi-providers-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/npi-providers-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.0-blueviolet.svg?style=flat-square)](https://bun.sh/)

</div>

<div align="center">

[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/npi-providers-mcp-server/releases/latest/download/npi-providers-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=npi-providers-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvbnBpLXByb3ZpZGVycy1tY3Atc2VydmVyIl19) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22npi-providers-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fnpi-providers-mcp-server%22%5D%7D)

[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)

</div>

<div align="center">

**Public Hosted Server:** [https://npi-providers.caseyjhand.com/mcp](https://npi-providers.caseyjhand.com/mcp)

</div>

---

## 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 full 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 complete NPPES record for up to 10 NPIs — taxonomies, addresses, credentials, identifiers, endpoints, and status. |
| `npi_lookup_taxonomy` | Resolve, fetch, or browse the NUCC Healthcare Provider Taxonomy — fully offline. |

### Resources

| Resource | Description |
|:---|:---|
| `npi://provider/{npi}` | A single provider's full 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` <sub>tool</sub>

- 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
- Plain-language `specialty` resolves through the bundled NUCC taxonomy to the registry's exact description before searching, echoed back via `resolvedTaxonomies` / `appliedTaxonomyDescription`; `taxonomy_description` is an escape hatch for an already-known exact description (mutually exclusive with `specialty`)
- Trailing-wildcard (`*`) name/organization matching requires at least 2 leading characters
- `limit` 1–200 (default 10), `skip` 0–1000; the registry never reports a true match total, only the first 1200 matches are reachable, and the response discloses page-size-not-total via `truncated` / `notice`
- Typed error reasons: `no_search_criteria`, `conflicting_specialty`, `unresolved_specialty`, `invalid_search_field`

---

### `npi_get_provider` <sub>tool</sub>

- Accepts a single NPI or up to 10; each is validated as exactly 10 digits before any API call
- Returns every taxonomy (with primary flag, license number and state), all practice and mailing addresses, credential, sex, sole-proprietor flag, enumeration and last-updated dates, secondary identifiers, and FHIR/Direct endpoints
- Three-way partition: `found` (resolved records), `notFound` (confirmed absence — deactivated or never enumerated), `errored` (upstream failure, distinct from absence — retry these)
- Throws `none_found` only when every requested NPI is a confirmed absence; an upstream failure on any NPI surfaces as that underlying error instead

---

### `npi_lookup_taxonomy` <sub>tool</sub>

- Three modes: `resolve` (plain-language term → matching codes/descriptions), `get` (exact code → full entry), `browse` (walk grouping → classification → specialization, filterable by grouping and NPI `section`)
- `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}` <sub>resource</sub>

- Returns the same fully decoded record as `npi_get_provider`, for one NPI, as `application/json`
- `npi` must be a well-formed 10-digit NPI; `no_record` when the registry has none (deactivated or never enumerated)

---

### `npi://taxonomy/{code}` <sub>resource</sub>

- Returns the same entry as `npi_lookup_taxonomy` mode `get`, 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`](https://github.com/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 879-code Healthcare Provider Taxonomy (v25.0) 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, with the 1200-match reachable ceiling surfaced when a broad query is capped
- Graceful partial failure — `npi_get_provider` returns per-NPI `found` / `notFound` / `errored` 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:

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

### Prerequisites

- [Bun v1.4.0](https://bun.sh/) 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