HelpDental MCP Server

A Model Context Protocol server that gives AI assistants access to 10,000+ UK dental practices and 32,000+ treatment prices.

Ask your AI assistant questions like:

• "Find a dentist near SW1A 1AA that does Invisalign"
• "How much does teeth whitening cost in Manchester?"
• "I need an emergency dentist in Birmingham"
• "Tell me about Bupa Dental Care in Leeds"
• "Book me in at the practice you just found, Tuesday at 10am" (booking tools, opt-in)

Installation

Via npx (recommended)

No installation needed. Configure your MCP client to run:

npx helpdental-mcp

Via npm (global)

npm install -g helpdental-mcp

Then run with:

helpdental-mcp

Configuration

The server requires a Supabase connection to the HelpDental database.

| Variable | Required | Description | |----------|----------|-------------| | SUPABASE_URL | Yes | HelpDental Supabase project URL | | SUPABASE_ANON_KEY | Yes | HelpDental Supabase anonymous key | | MCP_BOOKING_API_KEY | No | Set to enable the booking tools (book_appointment, confirm_booking_otp, get_booking_status). Without it the server only exposes the read-only search tools. | | HELPDENTAL_API_BASE | No | Override the HelpDental host. Defaults to https://helpdental.ai. |

Contact [email protected] for API access credentials.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "helpdental": {
      "command": "npx",
      "args": ["-y", "helpdental-mcp"],
      "env": {
        "SUPABASE_URL": "your-supabase-url",
        "SUPABASE_ANON_KEY": "your-anon-key"
      }
    }
  }
}

Claude Code

claude mcp add helpdental -- npx -y helpdental-mcp

Then set the environment variables in your shell before launching Claude Code.

Cursor / Windsurf / Other MCP Clients

Use stdio transport with the command npx -y helpdental-mcp and set the environment variables as above.

Available Tools

search_practices

Find dental practices near a UK postcode.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | postcode | string | Yes | UK postcode (e.g. "SW1A 1AA") | | treatment | string | No | Filter by treatment (e.g. "whitening", "implants") | | nhs_only | boolean | No | Only NHS-accepting practices | | limit | number | No | Max results (default 5, max 20) |

Example response:

{
  "practices": [
    {
      "name": "Smile Dental Clinic",
      "address": "123 High Street, London",
      "postcode": "SW1A 2AB",
      "google_rating": 4.7,
      "review_count": 312,
      "services": ["whitening", "implants", "invisalign"],
      "nhs_accepting": true,
      "consultation_fee": "from £50",
      "distance_miles": 0.3,
      "helpdental_url": "https://helpdental.ai/dental-practice/london/smile-dental-clinic"
    }
  ],
  "total": 42,
  "search_postcode": "SW1A 1AA"
}

get_treatment_prices

Get national and local average treatment prices across 24 categories.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | treatment | string | Yes | Treatment name (e.g. "teeth-whitening", "crown", "implant_single") | | postcode | string | No | UK postcode for local price comparison |

Supported treatments: check-up, whitening, crown, filling, root canal, extraction, implant, invisalign, veneer, bridge, hygienist, dentures, composite bonding, emergency, wisdom teeth, scale and polish, x-ray, mouthguard, sedation, and more.

Example response:

{
  "treatment": "whitening",
  "label": "Teeth Whitening",
  "national_average": "£350",
  "national_count": 1842,
  "local_average": "£395",
  "local_count": 67,
  "local_min": "£149",
  "local_max": "£795",
  "nhs_band": null,
  "postcode_area": "SW"
}

find_emergency_dentist

Find emergency dental care near a postcode. Returns up to 10 practices with emergency services, sorted by distance.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | postcode | string | Yes | UK postcode where emergency care is needed |

get_practice_details

Get full details for a specific practice including services, pricing, opening hours, CQC rating, and quality score.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | practice_id | number | No | Numeric practice ID | | practice_name | string | No | Practice name (partial match) |

One of practice_id or practice_name is required. When a single practice is matched, treatment prices are included in the response.

book_appointment

Book a real appointment at a UK practice. Only registered when MCP_BOOKING_API_KEY is set (see Booking section below).

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | practiceId | number | One of | Practice id from search_practices | | practiceSlug | string | One of | Practice slug | | slotDate | string | Yes | YYYY-MM-DD | | slotTime | string | Yes | 24h HH:MM | | patient | object | Yes | firstName, lastName, email, mobile always required. title, dob, addressLine1, postcode required for Dentally practices. | | appointmentType | string | Yes | consultation or emergency | | marketingOptIn | boolean | No | Defaults to true |

Returns { bookingId, status, message?, otpRequired?, depositUrl?, depositAmountPence? }.

The AI agent should always confirm the booking details with the user before calling this tool. It books a real appointment with a real practice.

confirm_booking_otp

Submit an SMS verification code for a Dentally booking that returned status: 'verification_needed'.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | bookingId | string | Yes | From book_appointment | | code | string | Yes | 4 to 6 digit SMS code |

get_booking_status

Poll the status of a booking.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | bookingId | string | Yes | From book_appointment |

Returns { status, message?, otpRequired?, depositUrl?, depositAmountPence?, depositPaidAt?, lastUpdated }. Status values: submitted, verification_needed, payment_required, done, failed, timeout.

Booking

The booking tools are off by default. They only register if you set MCP_BOOKING_API_KEY on the MCP server side. Without it, the server logs booking tools disabled on startup and exposes only the four read-only search tools.

Enabling

Add the env var to your client config:

{
  "mcpServers": {
    "helpdental": {
      "command": "npx",
      "args": ["-y", "helpdental-mcp"],
      "env": {
        "SUPABASE_URL": "...",
        "SUPABASE_ANON_KEY": "...",
        "MCP_BOOKING_API_KEY": "..."
      }
    }
  }
}

Contact [email protected] for a booking key.

How a booking flows

1. The agent calls book_appointment with the slot, patient, and appointment type.
2. It immediately gets back a bookingId and status: "submitted".
3. The agent polls get_booking_status every few seconds.
4. If status becomes verification_needed, an SMS code has been sent to the patient. The agent asks the user for the code and calls confirm_booking_otp.
5. If status becomes payment_required, a small deposit is needed. The agent shows the depositUrl to the user. Stripe takes the payment and the booking finalises in the background.
6. Status done means the slot is confirmed. Status failed or timeout means it did not complete.

Rate limits

Conservative on day one. Easy to loosen later.

• 5 booking attempts per IP per hour
• 3 booking attempts per email per 24 hours
• 10 booking attempts per target postcode area per hour

Bookings tagged with additional_data.source = 'mcp' so we can analyse abuse patterns.

How It Works

• Queries the HelpDental database via Supabase REST API (PostgREST)
• Geocodes postcodes using postcodes.io (free, no API key needed)
• Calculates distances using the haversine formula
• Returns structured JSON that AI assistants present naturally

Data Sources

• Practice data: 10,000+ CQC-registered dental practices, enriched with Google Places ratings, photos, and reviews
• Pricing data: 32,000+ treatment prices extracted from practice websites, covering 24 categories
• NHS status: Verified against the NHS Find a Dentist directory
• Quality scores: Composite scoring based on ratings, reviews, services, and data completeness

Development

git clone https://github.com/tris686/helpdental.git
cd helpdental/mcp-server
npm install
npm run build
npm start

Watch mode for development:

npm run dev

License

MIT