Content
# NPI Lookup MCP Server
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/modelcontextprotocol)
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
```bash
# 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:
```bash
cp env.example .env
```
2. Edit `.env` with your settings:
```bash
# 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
```bash
# 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
```python
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
```python
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)**
```python
CACHE_TYPE=diskcache
DISK_CACHE_DIR=./cache
```
**Redis (Distributed)**
```python
CACHE_TYPE=redis
REDIS_URL=redis://localhost:6379/0
```
**Memory (Development)**
```python
CACHE_TYPE=memory
CACHE_MAX_SIZE=1000
```
### Matching Configuration
Adjust fuzzy matching sensitivity:
```python
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:
```bash
# 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
| Tool | Description | Parameters |
|------|-------------|------------|
| `search_providers` | Multi-parameter search | query, city, state, specialty, limit |
| `validate_npi` | Validate NPI number | npi |
| `get_provider_details` | Get full provider info | npi |
| `bulk_search` | Batch processing | providers[] |
### 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 [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- [CMS NPPES NPI Registry](https://npiregistry.cms.hhs.gov/) for the official API
- [Model Context Protocol](https://github.com/modelcontextprotocol) for the MCP specification
- [RapidFuzz](https://github.com/maxbachmann/RapidFuzz) for fuzzy string matching
## 📞 Support
- **Issues**: [GitHub Issues](https://github.com/yourusername/npi-lookup-mcp-server/issues)
- **Discussions**: [GitHub Discussions](https://github.com/yourusername/npi-lookup-mcp-server/discussions)
- **Documentation**: [Wiki](https://github.com/yourusername/npi-lookup-mcp-server/wiki)
## 🚦 Status
