salonrunner-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@salonrunner-mcp Find available slots for a haircut next Tuesday."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 bookable services (name, id, price) |
| List stylists; optionally only those who do a given service |
| Open slots for a service over a date range (optionally one provider) |
| Your upcoming appointments |
| Book a slot returned by |
| 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 |
| stdio (+ optional HTTP) | The |
| stdio | Your client login |
| both | Auto-discovered; set only if discovery fails |
| both | Salon booking granularity (default 15) |
| both |
|
| HTTP | Signs tokens + encrypts the credentials inside them; survives restarts/scale-to-zero (>=16 chars) |
| HTTP | This server's public URL, e.g. |
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-mcpThen 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 buildThen 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 instanceNo 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
Settings → Connectors → Add custom connector.
URL:
https://YOUR-APP.fly.dev/mcpClaude opens the connector's login screen → enter your salon id + username + password.
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:httpSecurity model
Two independent auth layers:
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.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=truefirst.SALONRUNNER_SLOT_MINUTESmust 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 toolsbook_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
Scored across 6 tools
Each tool has a unique purpose: booking, canceling, finding availability, listing appointments, providers, and services. No overlap or ambiguity.
All tools follow a consistent verb_noun pattern in snake_case (e.g., book_appointment, list_services). The pattern is uniform and predictable.
With 6 tools, the set is well-scoped for a salon booking MCP. It covers browsing and booking without being overly large or minimal.
The surface covers the full client-side booking lifecycle: browsing services and providers, checking availability, booking, listing appointments, and canceling. No obvious gaps.
Maintenance
Related MCP Connectors
Demo booking server for a fictional salon. Try confirm-first write tools in Claude or ChatGPT.
Find a salon, barber or studio, see free time, get the booking link. Serves claude.ai and ChatGPT.
Find open slots on any appty link and book solo providers. Providers manage bookings by API key.
Build, deploy, and sell AI agents for local-service businesses - from your IDE.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables 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.5MIT
- AlicenseNot gradedqualityCmaintenanceTurns 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
- AlicenseNot gradedqualityBmaintenanceEnables 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
- AlicenseAqualityBmaintenanceConnects 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.732 PyPIElastic 2.0