npi-providers-mcp-server

v0.1.2 pre-1.0

Look up US healthcare providers in the NPPES NPI registry and resolve NUCC specialty codes via MCP. STDIO or Streamable HTTP.

public 3 tools 2 resources protocol 2025-11-25 github cyanheads/npi-providers-mcp-server

npi-providers.caseyjhand.com/mcp

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

codex mcp add npi-providers-mcp-server --url https://npi-providers.caseyjhand.com/mcp

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

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

{
  "mcpServers": {
    "npi-providers-mcp-server": {
      "command": "bunx",
      "args": [
        "mcp-remote",
        "https://npi-providers.caseyjhand.com/mcp"
      ]
    }
  }
}

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

curl -X POST https://npi-providers.caseyjhand.com/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1.0.0"}}}'

Built on@cyanheads/mcp-ts-core v0.10.6

Tools

npi_search_providers

open-world

Search the NPPES NPI registry for individual practitioners and healthcare organizations by name, organization name, location, provider type, and specialty. The specialty filter accepts plain-language terms (e.g. "cardiologist", "endocrinologist in Seattle") and resolves them through the bundled NUCC taxonomy to the registry's exact taxonomy descriptions before searching; the resolved taxonomy is echoed back so you can see what was actually searched. Returns a compact row per provider — NPI, name, primary specialty, city/state, type, and active/deactivated status — suitable for disambiguation; call npi_get_provider with an NPI for the full record. At least one search criterion is required, and the registry rejects state-only searches (pair state with another filter). The registry never reports a true match total and only the first 1200 matches are reachable, so broad queries are capped — narrow with more filters.

read

invocation

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "npi_search_providers",
    "arguments": {}
  }
}

schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name_search": {
      "description": "Convenience shortcut: a single person's name, split into first/last heuristically. For precise control use first_name/last_name.",
      "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). 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.",
      "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. 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.",
      "type": "string"
    },
    "state": {
      "description": "2-letter state code (e.g. \"WA\"). The registry rejects state-only searches — pair it with another criterion.",
      "type": "string",
      "pattern": "^[A-Z]{2}$"
    },
    "postal_code": {
      "description": "Practice-location postal/ZIP code (5 or 9 digits).",
      "type": "string"
    },
    "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). Only the first 1200 matches are reachable; skip beyond 1000 silently returns the same window — narrow the query instead of paging further.",
      "type": "integer",
      "minimum": 0,
      "maximum": 1000
    }
  },
  "required": [
    "limit",
    "skip"
  ],
  "additionalProperties": false
}

view source ↗

npi_get_provider

open-world

Fetch the complete 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 a fully populated provider profile: every taxonomy with its primary flag, license number and state; all practice and mailing addresses; credential, sex, sole-proprietor flag; enumeration and last-updated dates; active/deactivated status; secondary identifiers (Medicaid, etc.); and FHIR/Direct endpoints. The 10-digit NPI format is validated before any API call. Reports partial success: well-formed NPIs with no registry record (deactivated or never enumerated) land in notFound rather than failing the whole call.

read

invocation

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "npi_get_provider",
    "arguments": {
      "npis": "<npis>"
    }
  }
}

schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "npis": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^\\d{10}$",
          "description": "A 10-digit National Provider Identifier."
        },
        {
          "minItems": 1,
          "maxItems": 10,
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^\\d{10}$",
            "description": "A 10-digit National Provider Identifier."
          },
          "description": "An array of up to 10 ten-digit NPIs."
        }
      ],
      "description": "A single 10-digit NPI, or an array of up to 10. Each is validated as exactly 10 digits before any API call."
    }
  },
  "required": [
    "npis"
  ],
  "additionalProperties": false
}

view source ↗

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 taxonomy codes and their canonical descriptions; mode `get` returns the full entry for an exact code; mode `browse` walks the hierarchy (grouping → classification → specialization), optionally filtered by grouping and by NPI section (Individual/NPI-1 vs Non-Individual/NPI-2). Grounding a plain-language specialty here before calling npi_search_providers ensures the correct taxonomy code is sent rather than returning nothing.

read

invocation

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "npi_lookup_taxonomy",
    "arguments": {
      "mode": "<mode>"
    }
  }
}

schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "mode": {
      "type": "string",
      "enum": [
        "resolve",
        "get",
        "browse"
      ],
      "description": "resolve: plain term → codes. get: exact code → entry. browse: walk the hierarchy."
    },
    "query": {
      "description": "For mode \"resolve\": the plain-language specialty term to resolve (e.g. \"pediatric cardiologist\").",
      "type": "string"
    },
    "code": {
      "description": "For mode \"get\": the exact NUCC taxonomy code (e.g. \"207RC0000X\").",
      "type": "string"
    },
    "grouping": {
      "description": "For mode \"browse\": filter to a top-level grouping by case-insensitive substring (e.g. \"physicians\").",
      "type": "string"
    },
    "section": {
      "description": "For mode \"browse\": 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 for resolve/browse (1–50). Ignored for get.",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  },
  "required": [
    "mode",
    "limit"
  ],
  "additionalProperties": false
}

view source ↗

Resources

npi-provider

A single provider's full decoded NPPES record by NPI number — the resource twin of npi_get_provider for one NPI. Read-only, stable URI, useful as injectable context when an NPI is already known.

uri npi://provider/{npi} mime application/json

npi-taxonomy

A single NUCC Healthcare Provider Taxonomy entry by code (grouping, classification, specialization, definition, display name, NPI section). The resource twin of npi_lookup_taxonomy mode "get". Fully offline.

uri npi://taxonomy/{code} mime application/json