Skip to main content
Glama

salonrunner-mcp

An MCP server that lets an AI assistant find, book, and cancel salon appointments through your personal SalonRunner / Rosy Salon Software client account — the same booking site many salons use.

It's self-hosted: you deploy your own instance. Run it locally as a tool (Claude Desktop, Cursor, Copilot CLI) where credentials stay on your machine, or as a remote connector for claude.ai where you log in with your SalonRunner account on the connector's login screen.

⚠️ Unofficial, uses undocumented endpoints, personal use only. Read DISCLAIMER.md.

Tools

Tool

What it does

list_services

List bookable services (name, id, price)

list_providers

List stylists; optionally only those who do a given service

find_availability

Open slots for a service over a date range (optionally one provider)

list_my_appointments

Your upcoming appointments

book_appointment

Book a slot returned by find_availability

cancel_appointment

Cancel by appointment id

Related MCP server: Main Street MCP

How it works

list/find/book/cancel
        │
   this server ──login──► app.salonrunner.com  (session cookie)
        │      ──authv2─► customer JWT (30 min, auto-refreshed)
        │      ──reads──► app.rosysalonsoftware.com/api/v2  (Bearer JWT)
        └──────writes───► /customer/appointments/{book,cancel}.json  (cookie)

customerId is discovered from your account after login; corporateId is read from the JWT. Availability is computed from the provider's per-service duration and the salon's slot grid (SALONRUNNER_SLOT_MINUTES, default 15).

Configuration

There are two ways to run it, and they get their salon credentials differently:

  • Local (stdio): credentials come from the environment (.env).

  • Remote (HTTP, claude.ai): credentials are entered on the connector's login screen and encrypted into the token — the server needs no salon credentials in its environment.

Variable

Used by

Notes

SALONRUNNER_SALON_ID

stdio (+ optional HTTP)

The id in your booking URL …/customer/login.htm?id=XXXXX. In HTTP mode it's optional — if set, it pre-fills the salon id on the connector's login screen (handy for single-salon deployments and re-auth)

SALONRUNNER_USERNAME / SALONRUNNER_PASSWORD

stdio

Your client login

SALONRUNNER_CUSTOMER_ID

both

Auto-discovered; set only if discovery fails

SALONRUNNER_SLOT_MINUTES

both

Salon booking granularity (default 15)

SALONRUNNER_READ_ONLY

both

true disables book/cancel while you try it out

SESSION_SIGNING_KEY

HTTP

Signs tokens + encrypts the credentials inside them; survives restarts/scale-to-zero (>=16 chars)

PUBLIC_URL

HTTP

This server's public URL, e.g. https://your-app.fly.dev

In HTTP mode the salon id + username + password are collected on the login screen (validated by a real SalonRunner login) and encrypted into the OAuth token, so one deployment can serve multiple salons and there are no salon secrets on the server.

Option A — Local (Claude Desktop / Cursor / Copilot CLI)

Published on npm as salonrunner-mcp. Install globally:

npm install -g salonrunner-mcp

Then point your client at the salonrunner-mcp command (no build, no absolute paths). Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "salonrunner": {
      "command": "salonrunner-mcp",
      "env": {
        "SALONRUNNER_SALON_ID": "21248",
        "SALONRUNNER_USERNAME": "you@example.com",
        "SALONRUNNER_PASSWORD": "your-password"
      }
    }
  }
}

Prefer no global install? Use "command": "npx" with "args": ["-y", "salonrunner-mcp"] and the same env.

npm install && npm run build

Then use "command": "node" with "args": ["/absolute/path/to/salonrunner-mcp/dist/stdio.js"] and the same env.

No hosting, no OAuth — credentials stay on your machine. Recommended if you don't need claude.ai.

Option B — Remote (claude.ai custom connector)

claude.ai can only use remote MCP servers, so you deploy your own instance.

Deploy to Fly.io

fly launch --no-deploy          # pick a unique app name; creates the app
fly secrets set \
  SESSION_SIGNING_KEY=$(node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))") \
  PUBLIC_URL=https://YOUR-APP.fly.dev
fly deploy
fly scale count 1               # in-memory MCP sessions: keep a single instance

No salon credentials are configured here — users supply them on the login screen. The server refuses to start without SESSION_SIGNING_KEY. Credentials are validated by a real SalonRunner login and then encrypted into the (signed) token, which claude.ai stores, so the app scales to zero between uses and you authorize only once — cold starts (~3s) are transparent and never re-prompt.

Connect in claude.ai

  1. Settings → Connectors → Add custom connector.

  2. URL: https://YOUR-APP.fly.dev/mcp

  3. Claude opens the connector's login screen → enter your salon id + username + password.

  4. The six tools appear in chat.

Run the remote server locally (testing)

SESSION_SIGNING_KEY=local-dev-please-change PUBLIC_URL=http://localhost:8787 npm run start:http

Security model

Two independent auth layers:

  1. claude.ai ↔ this server — OAuth 2.1 (PKCE + dynamic client registration). The login screen authenticates the user with a real SalonRunner login; the credentials are then AES-GCM encrypted and embedded inside the HMAC-signed token (keyed by SESSION_SIGNING_KEY). No server-side session store, so authorization survives restarts and scale-to-zero.

  2. this server ↔ SalonRunner — login → session cookie → short-lived JWT, auto-refreshed, using the credentials decrypted from the caller's token.

The server holds no salon credentials at rest — they live (encrypted) inside each user's token and are only decrypted in memory per request. One deployment can serve multiple salons. A leaked token can't be revoked individually; rotate SESSION_SIGNING_KEY to invalidate all tokens (everyone re-enters credentials once). Keep SESSION_SIGNING_KEY secret and serve only over HTTPS.

Notes & limitations

  • Built on undocumented customer endpoints; they can change without notice. Base URLs are configurable so you can adapt quickly.

  • Real bookings/cancellations incur the salon's cancellation-policy fees. Tools surface the service/provider/time before acting; consider running with SALONRUNNER_READ_ONLY=true first.

  • SALONRUNNER_SLOT_MINUTES must match your salon's scheduling grid (default 15) for accurate availability.

  • The officially documented, partner-only Rosy Salon Software API (api.salonrunner.com) is a separate product requiring a salon-issued ApiKey; this project does not use it.

License

MIT — see LICENSE. No warranty.

Available Tools

6 tools
book_appointmentBook an appointmentA

Book an appointment. startTime must be a value returned by find_availability ('YYYY-MM-DD HH:MM:SS'). End time is computed from the provider's service duration. This creates a REAL booking subject to the salon's cancellation policy.

Inputs: serviceId (required), startTime (required), providerId (required).

cancel_appointmentCancel an appointmentA

Cancel an existing appointment by appointmentId (from list_my_appointments). Cancellation fees may apply per the salon's policy.

Inputs: reason (required), appointmentId (required).

find_availabilityFind availabilityA

Find open appointment slots for a service in a date range (inclusive). Dates are YYYY-MM-DD. Optionally restrict to one providerId. Returns startable times with the matching provider.

Inputs: to (required), from (required), serviceId (required), limit, +1 more.

list_my_appointmentsList my appointmentsA

List the signed-in client's upcoming (non-cancelled) appointments.

Inputs: no named parameters.

list_providersList providersA

List stylists/providers who take online bookings. Optionally filter to those who perform a given serviceId.

Inputs: serviceId.

list_servicesList servicesA

List bookable services offered by the salon (name, id, price, base duration).

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a unique purpose: booking, canceling, finding availability, listing appointments, providers, and services. No overlap or ambiguity.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern in snake_case (e.g., book_appointment, list_services). The pattern is uniform and predictable.

    Tool Count5/5

    With 6 tools, the set is well-scoped for a salon booking MCP. It covers browsing and booking without being overly large or minimal.

    Completeness5/5

    The surface covers the full client-side booking lifecycle: browsing services and providers, checking availability, booking, listing appointments, and canceling. No obvious gaps.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Enables AI agents to look up businesses, find free appointment slots, book, list and cancel appointments at salons, barbershops, nail and brow studios and clinics. Works read-only without a customer login by returning a pre-filled booking link, and can also run against a built-in demo with sample businesses.
      5
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Turns a local business's menu, hours, and booking rules from one JSON config into voice-callable tools, so an Alexa+ assistant can answer questions, quote and place pickup orders, check order status, and book appointments with customer confirmation. Works for restaurants, barbershops, salons, and clinics as a self-hosted Streamable HTTP server with a live owner dashboard.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables small local businesses to offer Alexa+ voice booking from one self-hosted, multi-business deployment with strict per-business isolation. It supports finding businesses, searching slots, two-step booking, rescheduling and cancellation with deposits, cross-session memory, bookings for people you care for, agentic waitlist recovery, notifications, and an owner dashboard.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Connects a signed-in Mangomint account to Claude Code, ChatGPT, Cursor and other AI agents so they can book and move appointments, check daily schedules and stylist gaps, reply to client messages, and pull client lists using plain language. No Mangomint API key or public API is required, since the server works directly inside the user's own Mangomint account.
      7
      32 PyPI
      Elastic 2.0