Mac MCP

Screenshots

<p align="center"> <img src="assets/screenshots/mac-mcp-system-info.png" alt="Mac MCP checking CPU, RAM, battery, and disk from a Custom GPT" width="48%"> <img src="assets/screenshots/mac-mcp-git-commits.png" alt="Mac MCP listing latest Git commits from a local repository" width="48%"> </p>

Mac MCP is a local macOS MCP server for AI Agents, mainly for CustomGPT (ChatGPT). It exposes safe, structured HTTP endpoints and MCP tools for common desktop tasks: shell commands, files, processes, background jobs, macOS automation, browser control, screenshots, search, HTTP requests, and interactive user prompts.

It is designed for four common setups:

1. MCP clients that can connect to the /mcp endpoint.
2. Custom GPT Actions that need an OpenAPI schema and a public HTTPS URL, usually through ngrok.
3. Ability to handle all the things done just from your phone (app).
4. Replacing the Codex, with nearly unlimited prompt limits (3000 Thinking 'prompt' limits, not request.)

Security note: this server can control your Mac. Do not expose it without authentication. Use a strong MCP_API_KEY, keep MCP_ALLOW_NO_AUTH=false, and only share your ngrok URL with clients you trust.

Features

• Run zsh commands and inspect running processes.
• Start, monitor, read, and stop long-running background jobs.
• Read, write, move, copy, delete, search, and inspect files.
• Run AppleScript, open apps/URLs, use clipboard, notifications, reminders, screenshots, volume, and brightness.
• Control Safari or Google Chrome tabs, selectors, JavaScript, screenshots, scrolling, keys, coordinate clicks, and DOM snapshots.
• Ask the local user a question with a native macOS dialog during autonomous workflows.
• Use the same backend through MCP or REST endpoints for Custom GPT Actions.

Requirements

• macOS
• Python 3.10+
• Git
• ngrok account, if you want a public HTTPS URL for Custom GPT Actions
• Optional: brightness CLI for brightness control

brew install python git ngrok
brew install brightness   # optional

Installation

git clone https://github.com/bulutarkan/mac-mcp.git
cd mac-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
cp mcp_server/.env.example mcp_server/.env

Edit mcp_server/.env:

MCP_API_KEY=replace-with-a-long-random-token
MCP_ALLOW_NO_AUTH=false
MCP_ALLOW_SHELL=true
RATE_LIMIT_PER_MINUTE=120

# Paste your static ngrok domain here. Use only the domain, not https://
NGROK_DOMAIN=your-domain.ngrok-free.dev

Generate a token with:

python3 - <<'PY'
import secrets
print(secrets.token_urlsafe(48))
PY

Start, stop, restart, and status

After pip install -e ., the mac-mcp command is available inside the virtual environment:

mac-mcp start          # local server only
mac-mcp start --ngrok  # local server + ngrok tunnel
mac-mcp status
mac-mcp restart --ngrok
mac-mcp stop

Useful options:

mac-mcp start --host 127.0.0.1 --port 8000
mac-mcp start --ngrok --ngrok-domain your-domain.ngrok-free.dev
mac-mcp start --reload
mac-mcp stop --force

mac-mcp start starts only the local server on 127.0.0.1:8000. mac-mcp start --ngrok starts the local server and a managed ngrok tunnel in the background.

Logs are written to:

~/.mac-mcp/mac-mcp.log

You can also run the server directly:

uvicorn mcp_server.main:app --host 127.0.0.1 --port 8000

Local endpoints

The server exposes:

MCP:  http://127.0.0.1:8000/mcp
REST: http://127.0.0.1:8000/api/*

Example REST request:

curl -X POST http://127.0.0.1:8000/api/system_info \
  -H "Authorization: Bearer $MCP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Example command request:

curl -X POST http://127.0.0.1:8000/api/run \
  -H "Authorization: Bearer $MCP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command":"pwd && sw_vers","timeout_s":10}'

Getting a static ngrok dev domain

Custom GPT Actions require a public HTTPS URL. For local development, ngrok is the easiest option.

1. Sign in or create an ngrok account.
2. Install and authenticate ngrok:

ngrok config add-authtoken YOUR_NGROK_AUTHTOKEN

3. Create a static domain in the ngrok dashboard:

Cloud Edge / Domains -> New Domain

You will get a domain like:

your-domain.ngrok-free.dev

4. Paste the static domain into mcp_server/.env:

NGROK_DOMAIN=your-domain.ngrok-free.dev

Use only the domain. Do not include https:// in NGROK_DOMAIN.

5. Start Mac MCP and ngrok together:

mac-mcp start --ngrok

This starts the local server at http://127.0.0.1:8000 and the public ngrok tunnel at:

https://your-domain.ngrok-free.dev

You can also override the domain from the command line:

mac-mcp start --ngrok --ngrok-domain your-domain.ngrok-free.dev

Custom GPT Actions setup

Use the included OpenAPI file:

openapi/custom-gpt-actions.json

Before importing it into the GPT builder, replace the placeholder server URL:

"servers": [
  {
    "url": "https://your-static-ngrok-domain.ngrok-free.dev"
  }
]

with your own ngrok domain:

"servers": [
  {
    "url": "https://your-domain.ngrok-free.dev"
  }
]

In the GPT builder:

1. Open your GPT.
2. Go to Configure -> Actions.
3. Create a new action.
4. Import openapi/custom-gpt-actions.json.
5. Set Authentication to API Key or Bearer token, depending on the UI.
6. Use this header format:

Authorization: Bearer YOUR_MCP_API_KEY

The REST endpoints are all under /api, and the operation IDs are stable. For example:

POST /api/run                 -> run_command
POST /api/system_info         -> get_system_info
POST /api/files               -> files_operation
POST /api/macos               -> macos_operation
POST /api/browser             -> browser_operation
POST /api/search              -> search_operation
POST /api/interactive         -> ask_user

OpenAPI format

A Custom GPT Action schema needs three main pieces:

{
  "openapi": "3.1.1",
  "info": {
    "title": "Mac MCP Server",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://your-domain.ngrok-free.dev"
    }
  ],
  "paths": {
    "/api/system_info": {
      "post": {
        "operationId": "get_system_info",
        "summary": "Get macOS system information",
        "responses": {
          "200": {
            "description": "Successful response."
          }
        }
      }
    }
  }
}

For grouped endpoints such as /api/files, /api/macos, /api/browser, and /api/search, the tool field selects the internal operation. Example:

{
  "tool": "read_file",
  "path": "~/Desktop/example.txt"
}

Browser example:

{
  "tool": "browser_open_url",
  "browser": "Google Chrome",
  "url": "https://example.com",
  "new_tab": true
}

MCP endpoint

Clients that support MCP over streamable HTTP can connect to:

https://your-domain.ngrok-free.dev/mcp

Use the same bearer token if authentication is enabled.

Security recommendations

• Keep MCP_ALLOW_NO_AUTH=false when using ngrok.
• Use a long random MCP_API_KEY.
• Prefer 127.0.0.1 for the local bind address.
• Do not commit .env, logs, job outputs, screenshots, or personal files.
• Review every tool you expose to AI clients. Shell, file, browser, and AppleScript tools are powerful.
• Stop the server and the managed ngrok tunnel when you are not using them:

mac-mcp stop

Repository structure

mcp_server/                  Python server and tool implementations
openapi/custom-gpt-actions.json
pyproject.toml               Package metadata and mac-mcp CLI entry point
README.md

License

MIT