helpdental-mcp

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 [e-mail] 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 [e-mail] for a booking key.

How a booking flows

• The agent calls book_appointment with the slot, patient, and appointment type.
• It immediately gets back a bookingId and status: "submitted".
• The agent polls get_booking_status every few seconds.
• 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.
• 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.
• 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