PopHIVE MCP Server

Featured on Claude, try it out here: https://claude.ai/directory/ant.dir.gh.cicatriiz.pophive

A Model Context Protocol (MCP) server that provides access to PopHIVE (Population Health Information Visual Explorer) public health data from Yale School of Public Health. This server exposes comprehensive health surveillance data including immunizations, respiratory diseases, and chronic diseases through standardized MCP tools, resources, and prompts.

🎯 Production-Ready: All critical bugs fixed, enhanced error handling, and comprehensive dataset metadata included.

📦 Desktop Extension Ready: Fully compliant with Anthropic's Desktop Extension (DXT) specification for one-click installation in Claude Desktop and other MCP-enabled applications.

What is PopHIVE?

PopHIVE (Population Health Information Visual Explorer) is Yale's comprehensive platform that aggregates near real-time public health data from authoritative sources including CDC surveillance systems, Epic Cosmos EHR networks, and Google Health Trends. It's an invaluable resource for epidemiologists, researchers, and public health professionals.

👉 Explore PopHIVE: https://www.pophive.org/

Recent Improvements

New Features

Performance Improvements

Bug Fixes

Overview

PopHIVE aggregates near real-time health data from multiple authoritative sources:

• CDC National Immunization Survey (NIS): Gold-standard vaccination coverage data

• Epic Cosmos EHR Network: Real-world clinical data from electronic health records

• CDC Laboratory Surveillance (NREVSS): Respiratory virus test positivity rates

• CDC Wastewater Surveillance (NWWS): Environmental viral monitoring

• Google Health Trends: Population behavior and symptom search patterns

Features

🔧 MCP Tools

• filter_data: Filter datasets by state, date range, demographics, and conditions

• compare_states: Compare health metrics across multiple states with statistical analysis

• time_series_analysis: Analyze trends over time with aggregation options

• get_available_datasets: Comprehensive catalog of all available datasets

• search_health_data: Search across datasets for specific conditions or keywords

📊 MCP Resources

• dataset://immunizations_nis: CDC National Immunization Survey data

• dataset://immunizations_epic: Epic Cosmos immunization data by demographics

• dataset://respiratory_ed: Emergency department visits for respiratory viruses

• dataset://respiratory_lab: Laboratory test positivity rates

• dataset://respiratory_wastewater: Wastewater viral surveillance data

• dataset://respiratory_trends: Google search trends for respiratory symptoms

• dataset://chronic_obesity: Obesity prevalence by state and age group

• dataset://chronic_diabetes: Diabetes prevalence and glycemic control data

• dataset://hospital_capacity: HHS hospital capacity data

• dataset://injury_overdose: CDC injury and overdose data

• dataset://youth_ed_mental_health: CDC youth mental health ED visit data

💡 MCP Prompts

• immunization_gaps: Analyze vaccination coverage gaps by demographics

• respiratory_surge_detection: Detect and analyze respiratory disease surges

• chronic_disease_trends: Analyze chronic disease prevalence trends

• multi_source_analysis: Comprehensive analysis integrating multiple data sources

Installation

Option 1: Desktop Extension (Recommended)

For Claude Desktop users:

1. Download the .dxt file from the releases page

2. Double-click the file to open with Claude Desktop

3. Click "Install" in the installation dialog

4. Configure any required settings (update frequency, cache size)

5. The extension will be automatically available in Claude Desktop

For other MCP-enabled applications:

• Use the same .dxt file with any application supporting Desktop Extensions

• Follow your application's extension installation process

Option 2: Manual Installation

Prerequisites:

• Node.js 18+

• npm or yarn

Setup:

1. Clone and install dependencies:

2. Configure environment (optional):

3. Test the server:

4. Start the server:

Option 3: Build Your Own Extension

Create a Desktop Extension from source:

1. Install DXT CLI tools:

2. Clone and prepare:

3. Package as extension:

4. Install the generated in Claude Desktop or other MCP applications

Configuration

Environment Variables

MCP Client Configuration

Add to your MCP client configuration (e.g., Claude Desktop):

Dataset Selection Guide

Choose the right dataset for your analysis:

Quick Dataset Selection

For national trends: Use immunizations_nis, respiratory_lab, or any dataset with geography="national"

For state comparisons: Use respiratory_ed, chronic_obesity, chronic_diabetes, or immunizations_nis

For real-time surveillance: Use respiratory_ed, respiratory_wastewater, or respiratory_trends

For clinical outcomes: Use immunizations_epic, chronic_obesity, or chronic_diabetes

Usage Examples

Basic Data Filtering

State Comparison

Time Series Analysis

Search Health Data

Using Prompts

Common Issues & Solutions

Issue: "No data found" or 0 results

Cause: Geographic mismatch or dataset limitations

Solutions:

1. Check dataset capabilities: Use get_available_datasets to see supported geographies

2. Use correct geography values:

   • For national data: "geography": "national" (not "US")

   • For states: Use state codes ("CA") or full names ("California")

3. Try alternative datasets: Some datasets only support national-level analysis

Issue: Empty results for state-level queries

Cause: Dataset only contains national-level data

Solutions:

1. Check dataset metadata first using get_available_datasets

2. Use state-capable datasets: respiratory_ed, chronic_obesity, chronic_diabetes, immunizations_nis

3. Switch to national analysis for datasets like respiratory_lab

Issue: Metric not found

Cause: Incorrect metric name or dataset mismatch

Solutions:

1. Use dataset-appropriate metrics:

   • Immunizations: coverage_rate, sample_size

   • Respiratory: ed_visits_per_100k, positivity_rate

   • Chronic: prevalence_rate, patient_count

2. Check sample data using get_available_datasets with include_sample: true

Working Parameter Combinations

Immunization Analysis

Respiratory Surveillance

Chronic Disease Analysis

Data Sources & Quality

Immunization Data

• NIS Data: Household survey, gold standard for coverage rates

• Epic Cosmos: EHR data with demographic breakdowns

• Update Frequency: Annual (NIS), Monthly (Epic)

• Geographic Level: State

• Quality: High confidence, large sample sizes

Respiratory Disease Surveillance

• ED Visits: Near real-time healthcare utilization

• Lab Data: Clinical test positivity rates

• Wastewater: Environmental viral monitoring (early indicator)

• Search Trends: Population behavior signals

• Update Frequency: Weekly

• Quality: High for clinical data, moderate for environmental/behavioral

Chronic Disease Data

• Source: Epic Cosmos EHR network

• Metrics: Clinical measurements (BMI, HbA1c)

• Update Frequency: Quarterly

• Geographic Level: State with age stratification

• Quality: High - real-world clinical data

API Reference

Tools

filter_data

Filter datasets by various criteria.

Parameters:

• dataset (required): Dataset identifier

• state (optional): State code or name

• start_date (optional): Start date (YYYY-MM-DD)

• end_date (optional): End date (YYYY-MM-DD)

• age_group (optional): Age group filter

• condition (optional): Condition/metric filter

compare_states

Compare health metrics across multiple states.

Parameters:

• dataset (required): Dataset identifier

• states (required): Array of state codes/names

• metric (required): Metric to compare

• time_period (optional): Time period for comparison

time_series_analysis

Analyze trends over time.

Parameters:

• dataset (required): Dataset identifier

• metric (required): Metric to analyze

• geography (optional): Geographic focus

• start_date (optional): Analysis start date

• end_date (optional): Analysis end date

• aggregation (optional): Time aggregation (weekly, monthly, quarterly, yearly)

Resources

All resources return JSON data with standardized schemas:

Development

Project Structure

Adding New Data Sources

1. Create a scraper in server/scrapers/

2. Update data loader to include new datasets

3. Add resource mappings in the main server

4. Update tool logic to handle new data types

5. Create prompts for new analysis types

Testing

Data Refresh

The server automatically refreshes data based on the UPDATE_FREQUENCY setting. Manual refresh:

Troubleshooting

Common Issues

Server won't start:

• Check Node.js version (18+ required)

• Verify all dependencies installed: npm install

• Check for port conflicts

No data returned:

• Data may be initializing on first run

• Check data directory permissions

• Verify network connectivity for scraping

MCP client connection issues:

• Verify server path in client configuration

• Check server logs for errors

• Ensure MCP client supports stdio transport

Logging

Server logs are written to stderr and include:

• Data scraping activities

• Tool execution results

• Error messages and stack traces

Enable verbose logging:

Contributing

1. Fork the repository

2. Create a feature branch

3. Make changes with tests

4. Submit a pull request

Code Style

• Use ESLint configuration

• Follow existing patterns

• Add JSDoc comments for public APIs

• Include error handling

License

MIT License - see LICENSE file for details.

Support

• Issues: GitHub Issues

• Documentation: This README and inline code comments

• Data Questions: Refer to original PopHIVE sources

Acknowledgments

• Yale School of Public Health for PopHIVE initiative

• CDC for surveillance data systems

• Epic Systems for Cosmos EHR network data

• Model Context Protocol community for standards