Content
# 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
```bash
brew install python git ngrok
brew install brightness # optional
```
## Installation
```bash
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`:
```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:
```bash
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:
```bash
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:
```bash
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:
```text
~/.mac-mcp/mac-mcp.log
```
You can also run the server directly:
```bash
uvicorn mcp_server.main:app --host 127.0.0.1 --port 8000
```
## Local endpoints
The server exposes:
```text
MCP: http://127.0.0.1:8000/mcp
REST: http://127.0.0.1:8000/api/*
```
Example REST request:
```bash
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:
```bash
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:
```bash
ngrok config add-authtoken YOUR_NGROK_AUTHTOKEN
```
3. Create a static domain in the ngrok dashboard:
```text
Cloud Edge / Domains -> New Domain
```
You will get a domain like:
```text
your-domain.ngrok-free.dev
```
4. Paste the static domain into `mcp_server/.env`:
```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:
```bash
mac-mcp start --ngrok
```
This starts the local server at `http://127.0.0.1:8000` and the public ngrok tunnel at:
```text
https://your-domain.ngrok-free.dev
```
You can also override the domain from the command line:
```bash
mac-mcp start --ngrok --ngrok-domain your-domain.ngrok-free.dev
```
## Custom GPT Actions setup
Use the included OpenAPI file:
```text
openapi/custom-gpt-actions.json
```
Before importing it into the GPT builder, replace the placeholder server URL:
```json
"servers": [
{
"url": "https://your-static-ngrok-domain.ngrok-free.dev"
}
]
```
with your own ngrok domain:
```json
"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:
```text
Authorization: Bearer YOUR_MCP_API_KEY
```
The REST endpoints are all under `/api`, and the operation IDs are stable. For example:
```text
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:
```json
{
"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:
```json
{
"tool": "read_file",
"path": "~/Desktop/example.txt"
}
```
Browser example:
```json
{
"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:
```text
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:
```bash
mac-mcp stop
```
## Repository structure
```text
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
