medicaid

This MCP server exposes a unified Medicaid data API focused on state formulary coverage, pricing data, enrollment trends, and provider spending via a single, multi-method tool named medicaid_info. The server provides access to state formularies for CA, NY, OH, TX, and IL, NADAC pricing, Federal Upper Limits, Drug Rebate Program, State Drug Utilization, Enrollment trends, and a DuckDB-backed provider spending module that operates on a local Parquet dataset. Use the unified tool to perform searches, pricing lookups, enrollment analyses, and provider-level queries, all through clearly documented methods.

To use the server, start it with the provided command configuration and send requests to the corresponding methods. The primary entry point is the medicaid_info tool, which supports methods such as search_state_formulary, get_nadac_pricing, get_enrollment_trends, get_federal_upper_limits, get_drug_rebate_info, get_drug_utilization, and several DuckDB-backed provider spending methods. Each method accepts state, drug names, dates, price ranges, and identifiers like NPI or HCPCS as parameters. The API is designed to auto-enrich formulary results with NADAC pricing where applicable and to enable cross-state enrichment for Illinois formulary data using data from CA/NY/OH.

Example usage includes performing a state formulary search with pricing, retrieving NADAC pricing for a drug, or querying provider spending by HCPCS code or provider NPI. The DuckDB-backed provider spending section supports filtering by HCPCS code, provider NPI, and date ranges, returning aggregate or top-service results efficiently on a local Parquet file.

Prerequisites:

• Node.js (and npm) installed on your system
• Access to the repository containing the Medicaid MCP server code

Steps:

1. Ensure Node.js and npm are installed
   • macOS/Linux: curl -fsSL https://fnm.vercel.app/install.sh | bash or visit https://nodejs.org to install the LTS version
2. Clone the repository (or download the release): git clone https://github.com/openpharma-org/medicaid-mcp-server.git cd medicaid-mcp-server
3. Install dependencies npm install
4. Build the server (if a build step exists) npm run build
5. Run the server (using the provided config entry): node build/index.js
6. Verify the server is running by hitting the API endpoint or by using the medicaid_info tool

Note: If you are using the prebuilt image or a package release, follow the image/package-specific start commands provided in the release notes.

Environment variables and configuration options you may encounter:

• Ensure the local Parquet file for Provider Spending is downloaded before using provider spending methods: python scripts/download_medicaid_provider_spending.py
• The DuckDB-backed provider spending methods operate on a local Parquet file; ensure file access permissions and disk space are adequate (~2.9 GB dataset referenced in docs).
• NADAC, Federal Upper Limits, and state enrollment data may be cached with TTL-based refresh; adjust cache settings if you run into stale data issues.
• If Illinois enrichment is enabled, the server will cross-reference CA/NY/OH NDC data to augment IL formulary results (coverage noted as 61.7%).
• When filtering by NPI, you can choose the role via npi_role parameter: default to "billing" or switch to "servicing" if needed.
• For large queries, expect slightly higher response times during initial data loads or cache warm-up.