ivfind-mcp

Read-only Model Context Protocol server for ivfind.com — a directory of ~4,000 IV therapy providers in the United States. It exposes the ivfind public API (/api/v1) as five tools that AI assistants (Claude Desktop, Cursor, Windsurf, Zed, etc.) can call natively to answer user questions like "find mobile NAD+ IV therapy in Austin" or "what IV clinics are near 90210."

Install

No global install required. Most MCP clients will run the server on demand via npx:

npx -y ivfind-mcp

On first run, npx fetches the package from npm and spawns the server on stdio.

Configure

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "ivfind": {
      "command": "npx",
      "args": ["-y", "ivfind-mcp"],
      "env": {
        "IVFIND_API_KEY": "optional-key-for-higher-rate-limits"
      }
    }
  }
}

Location of the config file:

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

Cursor (.cursor/mcp.json) and Windsurf / Zed

The same JSON shape works for Cursor (~/.cursor/mcp.json or a project-level .cursor/mcp.json), Windsurf (~/.codeium/windsurf/mcp_config.json), and Zed (~/.config/zed/settings.json under context_servers). Example for Cursor:

{
  "mcpServers": {
    "ivfind": {
      "command": "npx",
      "args": ["-y", "ivfind-mcp"]
    }
  }
}

Environment variables

| Variable | Default | Description | | --- | --- | --- | | IVFIND_API_BASE_URL | https://ivfind.com/api/v1 | Base URL for the ivfind JSON API. Override only for local testing. | | IVFIND_API_KEY | (unset) | Optional ivfind API key sent as the X-API-Key header. Without it, requests may be rate-limited more aggressively. Sign up at https://ivfind.com/api. | | IVFIND_USER_AGENT | ivfind-mcp/<version> | User-agent sent on outbound requests. |

Tools

All five tools are read-only. They do not submit leads, unlock leads, claim providers, or mutate any ivfind data.

search_providers

Search for IV therapy providers by location and filters.

Input

| Param | Type | Description | | --- | --- | --- | | city | string | Partial match on city name. | | zip | string (5 digits) | US zip code. Geocoded to lat/lng unless lat/lng are also supplied. | | state | string | Two-letter US code (CA) or full name (California). | | lat | number | Explicit latitude. Takes precedence over zip/city. | | lng | number | Explicit longitude. Takes precedence over zip/city. | | service | string | Partial match on service name (e.g. NAD+, Myers Cocktail, Hydration). | | service_type | "mobile" \| "clinic" \| "all" | Default "all". | | radius_miles | number | Default 25. Applied when lat/lng are available. | | limit | integer | Default 20, max 100. |

Output A JSON envelope:

{
  "data": [ { "name": "...", "slug": "...", "city": "...", "services": ["..."], "profile_url": "..." } ],
  "meta": { "total": 0, "returned": 0, "filters": { "...": "..." } }
}

get_provider

Full record for a single provider.

Input { "slug": "acme-iv-therapy-los-angeles" }

Output The provider object under data.

list_services

List unique IV therapy service names across the directory.

No input. Returns an alphabetically sorted array of strings. Derived from a sample of providers and cached in-memory for an hour.

list_cities

List cities in a state with provider counts.

Input { "state": "CA" }

Output { "data": [ { "city": "Los Angeles", "count": 42 }, ... ] }, sorted by count descending.

list_states

List US states with at least one IV therapy provider.

No input. Returns { "data": [ { "state": "CA", "count": 600 }, ... ] }, sorted by count descending.

Errors

Tool failures return a structured error as a tool result (not a thrown exception), with isError: true and a JSON body describing the status code and upstream response. If the ivfind API returns 401/403/429 and no IVFIND_API_KEY is configured, the error includes a hint prompting the user to set one.

Known limitations / v2 roadmap

• No write endpoints. Tools for submit_lead, unlock_lead, claim_provider, and delete_my_data are intentionally excluded. They involve WA MHMDA consent flows, OTP verification, and $35-per-unlock Stripe charges — all of which need AI-specific safeguards before being exposed. See the design-decisions document for the full rationale.
• Derived aggregates. list_services, list_cities, and list_states aggregate from search_providers calls rather than hitting dedicated endpoints. A future /api/v1/services, /api/v1/cities, and /api/v1/states aggregate would be faster and more accurate. The in-memory 1-hour cache keeps the current approach cheap in practice.
• Stdio only. HTTP transport isn't exposed. Users who need a hosted MCP endpoint can wrap this package themselves.
• Clinic-only filtering is post-processed. The upstream API's mobile param doesn't have a first-class clinic filter, so service_type: "clinic" filters returned results client-side. Large result counts with heavy mobile representation may under-fill.

License

MIT © Sean Coles