AI assistants (MCP)

Butler ships a built-in Model Context Protocol (MCP) server, so AI assistants like Claude Code, Claude Desktop and Cursor can see and drive your local dev environment — list your sites, link a new one, enable HTTPS, start and stop services, grab a ready-to-paste .env, and read logs to debug a failing service.

It’s the same butler binary you already have — a third frontend over the daemon alongside the CLI and the app — so there’s nothing extra to install.

Start the server

The server runs over stdio, which means your MCP client launches it for you; you don’t run it by hand. Point your client at:

{
  "command": "butler",
  "args": ["mcp"]
}

Where that snippet goes depends on the client:

• Claude Code — add it from the terminal:

  claude mcp add butler -- butler mcp

• Claude Desktop — add a butler entry under mcpServers in claude_desktop_config.json (Settings → Developer → Edit Config).
• Cursor — add the same butler entry under mcpServers in your MCP settings.

The daemon must be running

The MCP server is a thin client of the Butler daemon — it just forwards requests. If Butler isn’t running (butler status), the tools return an error telling you the daemon isn’t reachable. Run butler system install once and the daemon stays running in the background.

To see the built-in help and the tool list from a terminal:

butler mcp --help

What the assistant can do

The server exposes two kinds of tools.

Read tools (no side effects)

Tool	What it returns
list_sites	Linked and parked sites — name, hostname, path, framework driver, PHP version, HTTPS state.
list_services	Services with state (RUNNING/STOPPED/…), listen port or socket, version, and resolved .env block.
list_components	Installed component binaries — type, version, sha256, update track.
service_env	The ready-to-paste Laravel .env block for a running service, with this instance’s host/port/socket filled in.
tail_log	Tail a Butler log file (e.g. to see why a service is in BACKOFF).

Action tools

Each action is gated by your MCP client — the assistant proposes it and you approve it before it runs.

Tool	What it does
link_site	Link a project directory as a site (optionally enabling HTTPS).
secure_site	Enable HTTPS for a site — issue a cert and trust the CA.
start_service	Start a service by name.
stop_service	Stop a service by name.
restart_service	Restart a service by name.
set_global_php	Set the global default PHP version.

Example prompts

Once connected, you can ask your assistant things like:

• “What sites do I have linked, and which ones are on HTTPS?”
• “Link ~/Sites/new-api and enable HTTPS.”
• “Give me the .env database block for my mysql-default service.”
• “My mysql-default service won’t start — tail its log and tell me why.”
• “Set my global PHP to 8.3.”

Safety notes

• Actions are approved by you. Every action tool (link, secure, start/stop, set PHP) goes through your MCP client’s approval flow — the assistant can’t change your environment without your say-so.
• tail_log is sandboxed. It only reads Butler’s own logs under ~/Library/Logs/Butler; a path that tries to escape that directory is refused, so a prompt-injected agent can’t read arbitrary files off your machine.
• It’s local. The server talks to the daemon over a Unix socket on your machine. Nothing is exposed to the network.