Easy!Appointments

Easy!Appointments MCP server

A remote MCP server that lets Claude, ChatGPT and other AI assistants work the front desk of an Easy!Appointments booking system: find open slots, look up customers, and book, move or cancel appointments.

It is built for the people who run the booking system, not only for developers:

• Sign in with OAuth. Staff connect their AI assistant with their own login. The Easy!Appointments API token never leaves the server.
• Two access levels per connection. Read only sees services, open times, customers and bookings. Front desk can also book, reschedule and cancel. Each person has a ceiling set by an administrator.
• Nothing changes without a preview. Every change is a two-step call: a preview the assistant shows to the person, then a confirmed call with an idempotency key, so a retried request never books twice.
• A call log. Every tool call is recorded with masked personal details, the Easy!Appointments requests it made and how long it took. Staff can see it, export it as CSV and disconnect any assistant.
• Gentle on Easy!Appointments. The API allows 100 requests per IP every two minutes. The server caches the catalog and open times and caps how many days one search covers.

Not affiliated with or endorsed by Easy!Appointments. Easy!Appointments is a trademark of its owner.

Tools

Easy!Appointments sends its usual confirmation, change and cancellation emails for every change made through the API.

Requirements

• Easy!Appointments 1.5 or newer with the API enabled (Settings > Integrations > API: set an API token). Tested with 1.6.1.
• PHP 8.3 or newer, or Docker.
• HTTPS in production. AI clients will not connect to a plain HTTP server on the internet.

Run the demo locally

The compose file starts Easy!Appointments 1.6.1, a mail catcher and this server, then seeds a fictional physio clinic with services, providers, customers and two weeks of bookings.

cp .env.docker.example .env.docker# Set APP_KEY (see the comment in the file) and EA_API_TOKEN (any long random string)docker compose up -d --buildsh demo/setup.sh

Then:

• MCP server: http://localhost:8000/mcp (sign in as [email protected] / demo-password-1)
• Easy!Appointments: http://localhost:8080 (administrator / administrator)
• Emails Easy!Appointments sent: http://localhost:8025

To check the whole flow without an AI client, run the end-to-end script. It registers an OAuth client, signs in, picks an access level and calls every tool, including a real booking that it then moves and cancels:

php demo/e2e.php http://localhost:8000 [email protected] demo-password-1 front_deskphp demo/e2e.php http://localhost:8000 [email protected] demo-password-1 read

To put the demo on a public server with HTTPS, follow docs/deploy-demo.md.

Install for a real booking system

With Docker:

docker run -d --name ea-mcp \  -e APP_KEY=base64:... \  -e APP_URL=https://mcp.example.com \  -e TRUSTED_PROXIES='*' \  -v ea-mcp-data:/data/app \  -p 8080:8080 \  ea-mcp-server

Put it behind your HTTPS load balancer or reverse proxy, or set SERVER_NAME=mcp.example.com and publish ports 80 and 443 to let the built-in Caddy get a certificate. Run php artisan schedule:work in a second container from the same image to prune old logs and expired tokens daily.

Without Docker it is a standard Laravel 13 app: composer install --no-dev, copy .env.example to .env, php artisan key:generate, php artisan passport:keys, php artisan migrate, and point your web server at public/.

Then link the booking system and add staff:

php artisan ea:connect "Maple Street Physio" https://booking.example.com   # asks for the API tokenphp artisan ea:user [email protected] --name="Anna" --level=front_desk       # asks for a password

--level is the most that person may grant an assistant. They still choose per assistant on the consent screen.

If ea:connect gets a 401 from a working token, your web server is not passing the Authorization header to PHP. On Apache with PHP-FPM add SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1 to the Easy!Appointments vhost.

Connect an AI assistant

Add https://your-server/mcp as a custom connector (Claude: Settings > Connectors; ChatGPT: a workspace connector in developer mode). The client registers itself, opens the sign-in page, and the person picks Read only or Front desk. They can change or remove that at any time on /dashboard.

Security model

• The Easy!Appointments API token is admin-level, so it is stored encrypted on this server and never sent to clients. Each person signs in with their own account and gets a short-lived token (1 hour, refreshable for 30 days) that only works here.
• Tools a connection may not use are not listed to the assistant, and are refused if called anyway.
• Writes need a confirmed second call with an idempotency key. The slot is checked again, uncached, right before booking.
• Names, emails, phone numbers, addresses, notes and search text are masked in the call log. Easy!Appointments error messages that echo customer records are stripped before they reach the assistant or the log.
• Logs are kept 90 days by default (MCP_LOG_RETENTION_DAYS).

Known limits

• The Easy!Appointments API cannot check availability while ignoring the booking being moved, so a reschedule that overlaps its own current time is refused with an explanation. Cancel and rebook in that case.
• Cancelling deletes the booking in Easy!Appointments; there is no soft cancel in the API.
• One server can link several Easy!Appointments instances, one per account. There is no self-service sign-up; an administrator adds people with ea:user.

Development

composer installcp .env.example .env && php artisan key:generate && php artisan passport:keys && php artisan migratephp artisan testvendor/bin/pint

Tests run against an in-memory fake of the Easy!Appointments API (tests/Support/FakeEasyAppointments.php). demo/e2e.php runs against a real instance.

License

MIT