# Unofficial US Commercial Insurance Formulary MCP Server

Model Context Protocol (MCP) server providing unified access to drug formulary data from US ACA marketplace health insurance plans.

## Features

- **Unified drug search** across ~15,000 plans from ~735 issuers
- **Coverage details**: tier levels, copays, coinsurance
- **Restriction info**: prior authorization, step therapy, quantity limits
- **Plan comparison**: compare drug coverage across plans
- **State filtering**: filter results by state
- **Full-text search**: fast drug name search with FTS5

## Installation

```bash
cd formulary-mcp-server
npm install
```

### Option 1: Download Pre-built Database

```bash
npm run download:db
```

### Option 2: Build Database from Source

```bash
# Download issuer index from CMS
npm run download:index

# Download formulary files for all issuers
npm run download:files

# Build SQLite database
npm run build:db
```

### Build and Run

```bash
npm run build
npm start
```

## Usage

```json
{
  "mcpServers": {
    "formulary": {
      "command": "node",
      "args": ["/path/to/formulary-mcp-server/build/index.js"]
    }
  }
}
```

## Tool: formulary_info

Single unified tool with multiple methods:

### Methods

| Method | Description | Required Params |
|--------|-------------|-----------------|
| `search_drug` | Search drugs by name | `drug_name` |
| `get_drug_details` | Get full drug info with coverage | `rxnorm_id` |
| `get_plan_formulary` | Get drugs covered by a plan | `plan_id` |
| `get_plan_details` | Get plan info and tier structure | `plan_id` |
| `compare_coverage` | Compare drug across plans | `rxnorm_id` |
| `search_plans` | Search plans by state/issuer | - |
| `get_restrictions` | Get PA/ST/QL requirements | `rxnorm_id` |
| `get_alternatives` | Find drugs in same tier | `rxnorm_id`, `plan_id` |
| `get_statistics` | Get database statistics | - |

### Example Usage

**Search for a drug:**
```json
{
  "method": "search_drug",
  "drug_name": "metformin",
  "state": "CA",
  "limit": 10
}
```

**Get drug details:**
```json
{
  "method": "get_drug_details",
  "rxnorm_id": "860975",
  "state": "CA"
}
```

**Compare coverage:**
```json
{
  "method": "compare_coverage",
  "rxnorm_id": "860975",
  "state": "TX",
  "limit": 20
}
```

**Get plan formulary:**
```json
{
  "method": "get_plan_formulary",
  "plan_id": "12345VA0010001",
  "tier": "GENERIC"
}
```

**Get restrictions:**
```json
{
  "method": "get_restrictions",
  "rxnorm_id": "860975",
  "plan_id": "12345VA0010001"
}
```

## Response Format

### Drug Search Response
```json
{
  "method": "search_drug",
  "query": "metformin",
  "count": 5,
  "results": [
    {
      "rxnorm_id": "860975",
      "drug_name": "Metformin Hydrochloride 500 MG Oral Tablet",
      "plan_count": 245,
      "tiers": ["GENERIC", "PREFERRED-BRAND"]
    }
  ]
}
```

### Drug Details Response
```json
{
  "method": "get_drug_details",
  "drug": {
    "rxnorm_id": "860975",
    "drug_name": "Metformin Hydrochloride 500 MG Oral Tablet"
  },
  "coverage_summary": {
    "total_plans": 245,
    "plans_with_pa": 12,
    "plans_with_st": 5,
    "plans_with_ql": 89
  },
  "coverage": [
    {
      "plan_id": "12345CA0010001",
      "drug_tier": "GENERIC",
      "prior_authorization": false,
      "step_therapy": false,
      "quantity_limit": true,
      "marketing_name": "Blue Shield Gold",
      "issuer_name": "Blue Shield of California",
      "copay_amount": 10.00,
      "coinsurance_rate": 0.20
    }
  ]
}
```

## Data Coverage

| Aspect | Coverage |
|--------|----------|
| **Plans** | ~5,500 ACA marketplace plans |
| **Issuers** | ~150 insurance companies |
| **Drugs** | ~13,000 unique medications |
| **Templates** | ~800 unique formulary templates |
| **States** | 15+ states |
| **Data** | Tier, PA, step therapy, quantity limits |

## Data Source

Data is sourced from the CMS QHP (Qualified Health Plan) Provider & Formulary APIs:
- https://github.com/CMSgov/QHP-provider-formulary-APIs
- https://data.healthcare.gov/

**Note:** This covers ACA marketplace plans only. Employer-sponsored and Medicare Advantage plans are not included.

## License

MIT

## References

- [CMS QHP Provider & Formulary APIs](https://github.com/CMSgov/QHP-provider-formulary-APIs)
- [DaVinci Drug Formulary IG](http://hl7.org/fhir/us/davinci-drug-formulary/)
- [CMS Interoperability APIs](https://www.cms.gov/priorities/key-initiatives/burden-reduction/interoperability)