pawelsloboda5/NPI_Lookup_MCP_Server

NPI Lookup MCP Server

A production-ready MCP (Model Context Protocol) server for healthcare provider validation using the official CMS NPPES NPI Registry API v2.1. This server enables AI agents to perform real-time lookups, validation, and fuzzy matching of healthcare providers using their National Provider Identifier (NPI).

🌟 Features

• Real-time NPI lookups via the official CMS NPPES API v2.1
• Intelligent fuzzy matching for provider names, addresses, and specialties
• Multi-tier caching (memory, Redis, disk) for optimal performance
• Bulk search capabilities for processing multiple providers
• MCP protocol support for seamless AI agent integration
• Comprehensive error handling with retry logic
• Rate limiting to respect API constraints
• Type-safe with Pydantic models throughout

🚀 Quick Start

Prerequisites

• Python 3.8 or higher
• pip package manager
• (Optional) Redis for distributed caching

Installation

# Clone the repository
git clone https://github.com/yourusername/npi-lookup-mcp-server.git
cd npi-lookup-mcp-server

# Install dependencies
pip install -r requirements.txt

# Install MCP SDK
pip install "mcp[cli] @ git+https://github.com/modelcontextprotocol/python-sdk.git"

# Install the package
pip install -e .

Configuration

1. Copy the environment template:

cp env.example .env

2. Edit .env with your settings:

# Basic configuration
CACHE_TYPE=diskcache  # Options: diskcache, redis, memory
LOG_LEVEL=INFO
MATCHING_THRESHOLD=85

# Optional Redis configuration
REDIS_URL=redis://localhost:6379/0

Running the Server

# Start the MCP server
python -m npi_lookup_mcp_server

# Run with debug logging
python -m npi_lookup_mcp_server --log-level DEBUG

# Test the installation
python -m npi_lookup_mcp_server --test

📖 Usage Examples

As an MCP Server

The server exposes several tools for AI agents:

• search_providers - Search by name, location, specialty, or NPI
• validate_npi - Validate an NPI number and get provider details
• get_provider_details - Get comprehensive provider information
• bulk_search - Process multiple providers at once

Python Client Usage

from ProviderSearchInput import NPILookupClient

async with NPILookupClient() as client:
    # Search by name and state
    results = await client.search_by_name("Mayo Clinic", state="MN")
    
    # Validate an NPI
    is_valid = await client.validate_npi("1234567890")
    
    # Search by location
    results = await client.search_by_location(city="San Francisco", state="CA")

Integration Example

from ProviderSearchInput import NPILookupClient, SearchParameters

# Multi-agent healthcare system integration
async def validate_provider(provider_data):
    async with NPILookupClient() as client:
        results = await client.search_by_name(
            provider_data["name"],
            city=provider_data.get("city"),
            state=provider_data.get("state")
        )
        
        if results.result_count > 0:
            best_match = results.providers[0]
            return {
                "npi": best_match.npi,
                "verified_name": best_match.provider_name,
                "taxonomies": best_match.taxonomies,
                "confidence": 0.95
            }

🏗️ Architecture

┌─────────────────────────────────┐
│        MCP Server               │  <- AI agents connect here
├─────────────────────────────────┤
│      NPILookupClient            │  <- High-level Python API
├─────────────────────────────────┤
│   MatchingEngine │ CacheManager │  <- Business logic layer
├─────────────────────────────────┤
│      CMSAPIClient               │  <- NPPES API integration
├─────────────────────────────────┤
│   Models & Configuration        │  <- Data structures
└─────────────────────────────────┘

🔧 Advanced Configuration

Cache Backends

DiskCache (Default)

CACHE_TYPE=diskcache
DISK_CACHE_DIR=./cache

Redis (Distributed)

CACHE_TYPE=redis
REDIS_URL=redis://localhost:6379/0

Memory (Development)

CACHE_TYPE=memory
CACHE_MAX_SIZE=1000

Matching Configuration

Adjust fuzzy matching sensitivity:

MATCHING_THRESHOLD=85  # 0-100, higher = stricter
MATCHING_ALGORITHM=WRatio  # Options: Ratio, Partial, TokenSort, WRatio

📊 Performance

• API Response Time: < 500ms average (without cache)
• Cache Hit Time: < 10ms
• Fuzzy Matching: < 50ms for 1000 providers
• Concurrent Requests: Handles 100+ simultaneous searches
• Rate Limiting: 1000 requests/hour (configurable)

🧪 Testing

Run the test suite:

# Run all tests
pytest

# Run with coverage
pytest --cov=ProviderSearchInput

# Run specific test categories
pytest -m "not slow"  # Skip slow tests
pytest -k "test_api"  # Run only API tests

📚 API Reference

MCP Tools

Resources

• npi://taxonomies - Healthcare specialty codes
• npi://statistics - Server performance metrics
• npi://config - Current configuration

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please ensure:

• All tests pass
• Code follows the existing style
• Documentation is updated
• Commit messages are descriptive

📄 License

This project is licensed under the MIT License - see the file for details.

🙏 Acknowledgments

• CMS NPPES NPI Registry for the official API
• Model Context Protocol for the MCP specification
• RapidFuzz for fuzzy string matching

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Wiki

🚦 Status