io.github.cyanheads/macos-mcp-server

Official

by cyanheads · TypeScript

Control macOS system settings, apps, windows, audio, displays, screenshots, and Focus mode via MCP.

Control macOS system settings, apps, windows, audio, displays, and Focus mode.

Topics

ai-agentsai-toolsautomationcyanheadsjxamacosmcpmcp-servermodel-context-protocolosascriptsystem-controltypescript

Install

Configuration

Environment variables

MACOS_SCREENSHOT_DIR

Default directory for screenshot files. Defaults to ~/Desktop when empty.

MACOS_DISPLAY_LAYOUTSdefault {}

JSON object mapping layout names to displayplacer argument strings for apply_layout.

MCP_LOG_LEVELdefault info

Minimum log level for output: debug, info, notice, warning, error.

MCP_HTTP_HOSTdefault 127.0.0.1

The hostname for the HTTP server.

MCP_HTTP_PORTdefault 3010

The port to run the HTTP server on.

MCP_HTTP_ENDPOINT_PATHdefault /mcp

The endpoint path for the MCP server.

MCP_AUTH_MODEdefault none

Authentication mode: none, jwt, or oauth.

claude_desktop_config.json

{
  "mcpServers": {
    "macos-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@cyanheads/macos-mcp-server@0.1.4",
        "run",
        "start:stdio"
      ],
      "env": {
        "MACOS_SCREENSHOT_DIR": "<YOUR_MACOS_SCREENSHOT_DIR>",
        "MACOS_DISPLAY_LAYOUTS": "{}",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}