NPPES Server

An MCP (Model Context Protocol) server for searching healthcare providers in the US National Provider Identifier (NPI) Registry — works with Claude, Cursor, and any MCP-compatible AI assistant.

Built with FastAPI, Redis caching, and FAISS-based semantic search over NUCC taxonomy codes.

Claude Integration

This server implements the MCP (Model Context Protocol) specification, making it compatible with:

• Claude Desktop (Anthropic)
• Cursor IDE
• Windsurf IDE
• Any MCP-compatible client

Once deployed, you can connect Claude to search NPI providers using natural language:

You: Find me 5 pediatricians in Hartford, Connecticut
Claude: [uses search_providers tool via MCP server]
→ Returns list of providers with NPI numbers, addresses, specialties

The MCP endpoint is at /mcp and accepts JSON-RPC 2.0 tools/call requests.

What This Does

Query the NPPES registry (npiregistry.cms.hhs.gov) using natural language or structured filters:

• Find providers by location: state=CT, city=Hartford
• Find by specialty: Search using taxonomy codes or semantic descriptions like "pediatric cardiologist"
• Caching: Redis (Upstash) caches results for 1 hour to stay friendly to the NPPES API

Quick Start

Local Development

# Clone and enter
git clone https://github.com/yourusername/nppes-mcp-server.git
cd nppes-mcp-server

# Set up virtual environment
python -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run the server
uvicorn app.main:app --reload

# Test it
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "search_providers",
      "arguments": {"state": "CT", "city": "Hartford", "limit": 3}
    }
  }'

With Docker

docker build -t nppes-mcp .
docker run -p 8000:8000 -e REDIS_URL=your_redis_url nppes-mcp

MCP Tools

This server exposes the following MCP tools via JSON-RPC 2.0 at the /mcp endpoint:

search_providers

Search for healthcare providers with filters:

{
  "name": "search_providers",
  "arguments": {
    "name": "John Smith",
    "first_name": "John",
    "last_name": "Smith",
    "organization_name": "Hospital",
    "city": "Hartford",
    "state": "CT",
    "specialty": "207Q00000X",
    "zip_code": "06106",
    "limit": 10
  }
}

get_provider_by_npi

Get full provider record by NPI number:

{
  "name": "get_provider_by_npi",
  "arguments": {
    "npi": "1000000023"
  }
}

validate_npi

Validate an NPI using Mod 97-10 checksum:

{
  "name": "validate_npi",
  "arguments": {
    "npi": "1000000023"
  }
}

get_npi_for_provider

Search for NPI numbers by provider name and location:

{
  "name": "get_npi_for_provider",
  "arguments": {
    "first_name": "John",
    "last_name": "Smith",
    "organization_name": "Medical Center",
    "city": "Hartford",
    "state": "CT",
    "zip_code": "06106",
    "specialty": "207Q00000X"
  }
}

resolve_taxonomy

Look up taxonomy codes by code or natural language:

{
  "name": "resolve_taxonomy",
  "arguments": {
    "query": "heart doctor"
  }
}

semantic_search

Combined RAG + NPPES search - finds providers matching a natural language query:

{
  "name": "semantic_search",
  "arguments": {
    "query": "find me a pediatric cardiologist in Connecticut",
    "state": "CT",
    "city": "Hartford",
    "top_k": 5,
    "min_score": 0.0
  }
}

Connecting to Claude

Once deployed, add this to your Claude Desktop config:

macOS

~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "nppes": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-http", "--port", "8000"],
      "env": {
        "URL": "https://your-app.onrender.com/mcp"
      }
    }
  }
}

Or using SSE transport

{
  "mcpServers": {
    "nppes": {
      "url": "https://your-app.onrender.com/mcp"
    }
  }
}

Then ask Claude:

"Find me 3 cardiologists in Boston, MA"

Claude will use the MCP tool to search and return provider results.

Environment Variables

Variable	Default	Description
REDIS_URL	redis://localhost:6379	Redis connection (Upstash for production)
CACHE_TTL_SECONDS	3600	Cache lifetime in seconds
NPPES_API_URL	(NPPES endpoint)	Override NPPES API URL
REQUEST_TIMEOUT_SECONDS	30	HTTP request timeout
LOG_LEVEL	INFO	Logging level

See .env.example for more.

Deployment

This repo deploys easily to Render.com:

1. Connect your GitHub repo to Render
2. Create a Web Service with Docker
3. Set REDIS_URL to your Upstash URL
4. Deploy

The render.yaml file handles most configuration automatically.

Testing

# All tests
pytest

# Just unit tests (fast)
pytest tests/unit -q

# E2E against live server (requires MCP_SERVER_URL env var)
MCP_SERVER_URL=https://your-server.com pytest tests/e2e -v

Tech Stack

• FastAPI - HTTP server
• httpx - Async HTTP client for NPPES API
• Redis (Upstash) - Caching layer
• FAISS - Vector similarity search
• sentence-transformers - Embeddings (paraphrase-MiniLM-L3-v2)
• pytest - Testing with 85%+ coverage

Test Coverage

# Run all tests
pytest

# Current coverage: ~85%
# 119 tests passing across unit, integration, and contract tests

Test Suite	Tests
tests/unit/	63 tests
tests/integration/	14 tests
tests/contract/	Schema validation
tests/e2e/	Live server tests

Why This Exists

I needed a way to query the NPI registry programmatically for a health-tech project. The NPPES web interface is... not great for programmatic access. This MCP server makes it easy for AI assistants (or any HTTP client) to search providers using natural language or structured filters.

The RAG pipeline over NUCC taxonomy codes lets you search by things like "find a doctor who treats heart conditions" instead of memorizing taxonomy codes.

License

Apache License 2.0 - see LICENSE file.

---

Built with Claude Code and a lot of coffee.