Skip to main content

MCP Server Integration

The MCP server exposes Mac Automation capabilities to agent frameworks (OpenAI MCP, custom LLM tooling, etc.).

1. Install dependencies​

cd Clients/MCPServer
npm install

2. Configure environment variables​

Copy .env.example to .env and set:

MAC_AUTOMATION_API_BASE_URL=http://localhost:4000/api
MAC_AUTOMATION_CLIENT_ID=mac-automation-cli
MAC_AUTOMATION_TENANT=optional-tenant

If you run the server in production, point MAC_AUTOMATION_API_BASE_URL at the load-balanced backend URL.

3. Authenticate once with the CLI​

The MCP server reuses the Keychain entry com.mac-automation.auth. Run mac-automation-cli login on the same host and approve the device. Tokens will then be available to the server.

4. Start the server​

npm run start

You should see logs resembling:

MCP Server listening on http://localhost:5174

Configure your agent to connect to this endpoint.

5. Token refresh & maintenance​

  • Tokens refresh automatically as long as the refresh token remains valid.
  • If refresh fails (e.g., you revoked the license), run the CLI login again and re-approve the device.
  • For high availability, run the MCP server under a process manager such as pm2, systemd, or inside Docker.