Run the connector on your machine

Some assistants cannot reach a server over the web — they only talk to a program running on your own computer. Codex, LM Studio and most self-hosted agents work this way. For those, install the Luna connector as a small program instead of pasting a Server URL.

If your assistant can take a URL — Claude, ChatGPT, Cursor — you do not need this page. Follow MCP keys instead, it is simpler and there is nothing to install.

If npx says the package cannot be found, this connector has not been released for your store's app version yet. Use the Server URL method on the MCP keys page in the meantime.

What you need

Node.js (opens in a new tab) 20 or later on the computer running the assistant
An MCP key — create one under Settings > Developers (see MCP keys)

Nothing to install by hand: npx fetches the connector the first time your assistant starts it, and picks up new releases on its own. If you would rather install it yourself, see Installing it yourself below.

🔌 Set it up

Add this to your assistant's MCP configuration. For Claude Desktop the file lives at ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "avada-booking": {
      "command": "npx",
      "args": ["-y", "@avada/booking-mcp"],
      "env": {
        "BOOKING_MCP_KEY": "mcp_your-key-here"
      }
    }
  }
}

Restart the assistant and ask it something simple, like "What is booked this week?".

Back in Settings > Developers, the key's status changes from Never used to the time it last answered — the quickest way to tell it really works.

Installing it yourself

npx reaches npm every time your assistant starts. Install the connector once instead if that does not suit you — a machine that is offline at startup, a slower launch than you want, or a version you have tested and would rather stay on:

npm install -g @avada/booking-mcp

The package installs a booking-mcp command, so the assistant points straight at it and needs no args:

{
  "mcpServers": {
    "avada-booking": {
      "command": "booking-mcp",
      "env": {
        "BOOKING_MCP_KEY": "mcp_your-key-here"
      }
    }
  }
}

To stay on one version, install that version — npm install -g @avada/[email protected] — and upgrade when you choose to. The npx form pins the same way, by putting the version in the package name: ["-y", "@avada/[email protected]"].

Either way you need the package on npm, which is what the note at the top of this page is about.

✍️ Letting it make changes

The connector is read-only by default, even when your key has permission to make changes. It takes one extra line to allow them:

"env": {
  "BOOKING_MCP_KEY": "mcp_your-key-here",
  "BOOKING_MCP_ENABLE_WRITES": "true"
}

⚠️

"true" must be in quotes. Written as true without quotes, your assistant rejects the whole configuration file with an error like "not a valid MCP server configuration".

Holding a key is not the same as agreeing to let an assistant change your calendar, so we ask for both: the permission on the key and this line. Turning it on never grants more than the key already carries — a read-only key stays read-only.

⚙️ Settings

Variable	Required	What it does
`BOOKING_MCP_KEY`	Yes	Your key from Settings > Developers (`mcp_…`)
`BOOKING_MCP_ENABLE_WRITES`	No	`"true"` (quoted) to allow changes. Ignored for permissions the key does not carry
`BOOKING_API_URL`	No	Defaults to the app. Only the app's own addresses are accepted — your key travels in a request header, so it is never sent anywhere else

🕐 About dates and times

Every date and time is wall-clock time in your store's timezone, not UTC. Asking for "10am Friday" books 10am as your staff read it on the wall, wherever the assistant happens to be running.

The assistant reads your timezone from your settings before booking, so nothing is needed from you — but do give it the Settings read permission if you want it to book accurately.

🔍 Which tools appear

Only the ones your key allows. Untick a permission and the matching tool does not exist for that assistant at all — it never sees it, so it never tries. See What each permission unlocks for the full list.

Write tools additionally need BOOKING_MCP_ENABLE_WRITES above.

🧯 If something goes wrong

Your assistant shows the connector's messages in its MCP log panel.

Message	What it means
`Missing BOOKING_MCP_KEY`	The `env` block is missing, or the key is an empty string
`Authentication failed`	The key is wrong or was deleted — create a new one
`This key has expired`	Keys expire on the schedule you picked; create a new one
`is not a Booking app host`	`BOOKING_API_URL` points somewhere your key must never be sent
`does not have the "…" permission`	Tick that permission on the key, or ask the assistant to do something else
`Rate limited`	60 requests per minute per key — wait about half a minute
A tool is missing	The key lacks that permission, or changes are not enabled

Good to know

The connector runs on your computer and talks only to your store's app — no data passes through anywhere else.
Deleting or regenerating the key cuts the connector off immediately; paste the new value and restart the assistant.
One key can serve several assistants, but a separate key per assistant is safer: you can revoke one without disturbing the rest, and the usage timestamps stay meaningful.

Permissions REST API