Package Exports

@fhirfly-io/mcp-server

Readme

@fhirfly-io/mcp-server

MCP (Model Context Protocol) server for connecting Claude Desktop to FHIRfly healthcare reference data APIs.

What is this?

This package lets Claude Desktop look up real healthcare reference data including:

NDC - Drug products and packages (FDA)
NPI - Healthcare provider identifiers (CMS)
RxNorm - Drug terminology (NLM)
LOINC - Laboratory codes (Regenstrief Institute)
ICD-10 - Diagnosis and procedure codes (CMS)
CVX/MVX - Vaccine codes (CDC)
FDA Drug Labels - Prescribing information

When you ask Claude about medications, providers, or clinical codes, it can look up accurate, current information instead of relying on training data.

Prerequisites

Claude Desktop - Download from claude.ai/download
Node.js 18+ - Download from nodejs.org
FHIRfly API Key - Get one at fhirfly.io (free tier available)

Quick Setup

Step 1: Get a FHIRfly API Key

Go to fhirfly.io and sign up
Navigate to Dashboard > Credentials
Click Create Credential and select MCP (Claude Desktop)
Copy your API key (starts with ffly_)

Step 2: Configure Claude Desktop

Find your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the FHIRfly server configuration:

{
  "mcpServers": {
    "fhirfly": {
      "command": "npx",
      "args": ["-y", "@fhirfly-io/mcp-server"],
      "env": {
        "FHIRFLY_API_KEY": "ffly_live_your_key_here"
      }
    }
  }
}

Replace ffly_live_your_key_here with your actual API key.

Step 3: Restart Claude Desktop

Completely quit Claude Desktop and reopen it. The FHIRfly tools should now be available.

Verify It Works

Try asking Claude:

"What is NDC 0069-0151-01?"
"Look up NPI 1234567893"
"Search for COVID vaccines in the CVX database"
"What are the drug interactions for Lipitor?"

Claude should use the FHIRfly tools to look up real data.

Available Tools

Tool	Description
`ndc_get`	Look up drug by NDC code
`ndc_search`	Search drugs by name, ingredient, etc.
`npi_get`	Look up provider by NPI number
`npi_search`	Search providers by name, specialty, location
`rxnorm_get`	Look up drug by RxCUI
`rxnorm_search`	Search drug terminology
`loinc_get`	Look up lab test by LOINC code
`loinc_search`	Search lab codes
`icd10_get`	Look up diagnosis/procedure code
`icd10_search`	Search ICD-10 codes
`cvx_get`	Look up vaccine by CVX code
`cvx_search`	Search vaccine codes
`mvx_get`	Look up vaccine manufacturer
`mvx_search`	Search manufacturers
`fda_label_lookup`	Look up FDA drug label
`fda_label_search`	Search drug labels
`fda_label_safety`	Get safety info (boxed warnings, contraindications)
`fda_label_interactions`	Get drug interaction info
`fda_label_dosing`	Get dosing information
`fda_label_sections`	Get specific label sections

Configuration Options

Environment Variable	Description	Default
`FHIRFLY_API_KEY`	Your FHIRfly API key (required)	-
`FHIRFLY_API_URL`	API base URL	`https://api.fhirfly.io`
`FHIRFLY_DEBUG`	Enable debug logging (`1` or `true`)	`false`

Troubleshooting

"FHIRFLY_API_KEY environment variable is required"

Your API key isn't configured. Make sure:

You have a valid API key from fhirfly.io
It's set in the env section of your Claude Desktop config
The key starts with ffly_

"Invalid API key format"

FHIRfly API keys start with ffly_. Check that you copied the full key.

"Authentication failed"

Your API key may be invalid or expired. Generate a new one at fhirfly.io/dashboard/credentials.

Claude doesn't show FHIRfly tools

Make sure you completely quit and restarted Claude Desktop
Check your config file syntax (must be valid JSON)
Enable debug mode to see what's happening:

{
  "mcpServers": {
    "fhirfly": {
      "command": "npx",
      "args": ["-y", "@fhirfly-io/mcp-server"],
      "env": {
        "FHIRFLY_API_KEY": "your_key",
        "FHIRFLY_DEBUG": "1"
      }
    }
  }
}

"Rate limit exceeded"

You've hit your plan's rate limit. Wait a moment and try again, or upgrade your plan at fhirfly.io.

How It Works

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Claude Desktop │────▶│  This Package   │────▶│  FHIRfly API    │
│                 │     │  (runs locally) │     │  (cloud)        │
│  "What is       │◀────│                 │◀────│                 │
│   NDC 123..."   │     │  Translates MCP │     │  Returns drug   │
│                 │     │  ↔ HTTPS        │     │  data           │
└─────────────────┘     └─────────────────┘     └─────────────────┘

This package runs on your computer as a bridge between Claude Desktop and the FHIRfly API. It:

Receives requests from Claude Desktop via stdin
Translates them to HTTPS requests to FHIRfly
Returns the results to Claude via stdout

Your API key is sent to FHIRfly over HTTPS. No healthcare data is stored locally.

License

MIT - see LICENSE

JSPM