内容
# Mac MCP
## 截图
<p align="center">
<img src="assets/screenshots/mac-mcp-system-info.png" alt="Mac MCP 检查 CPU、RAM、电池和磁盘信息" width="48%">
<img src="assets/screenshots/mac-mcp-git-commits.png" alt="Mac MCP 列出本地仓库的最新 Git 提交记录" width="48%">
</p>
Mac MCP 是一个本地的 macOS MCP 服务器，主要用于 AI 代理，特别是 CustomGPT（ChatGPT）。它提供了安全、结构化的 HTTP 端点和 MCP 工具，用于常见的桌面任务：shell 命令、文件、进程、后台作业、macOS 自动化、浏览器控制、截图、搜索、HTTP 请求和交互式用户提示。
它设计用于四种常见的设置：
1. 可以连接到 `/mcp` 端点的 MCP 客户端。
2. 需要 OpenAPI 模式和公共 HTTPS URL 的 Custom GPT 操作，通常通过 ngrok 实现。
3. 能够处理所有仅从手机（应用程序）完成的事情。
4. 替换 Codex，具有几乎无限的提示限制（3000 个思考提示限制，而不是请求）。
> 安全注意：此服务器可以控制您的 Mac。在没有身份验证的情况下，请勿公开它。使用强大的 `MCP_API_KEY`，保持 `MCP_ALLOW_NO_AUTH=false`，并仅与您信任的客户端共享 ngrok URL。
## 功能
- 运行 zsh 命令并检查正在运行的进程。
- 启动、监控、读取和停止长期运行的后台作业。
- 读取、写入、移动、复制、删除、搜索和检查文件。
- 运行 AppleScript、打开应用程序/URL、使用剪贴板、通知、提醒、截图、音量和亮度。
- 控制 Safari 或 Google Chrome 标签页、选择器、JavaScript、截图、滚动、按键、坐标点击和 DOM 快照。
- 在自主工作流期间，向本地用户提问，使用原生 macOS 对话框。
- 通过 MCP 或 REST 端点为 Custom GPT 操作使用相同的后端。
## 要求
- macOS
- Python 3.10+
- Git
- ngrok 账户（如果您想要一个用于 Custom GPT 操作的公共 HTTPS URL）
- 可选：`brightness` CLI 用于亮度控制
```bash
brew install python git ngrok
brew install brightness # 可选
```
## 安装
```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
```
编辑 `mcp_server/.env`:
```env
MCP_API_KEY=替换为一个长随机令牌
MCP_ALLOW_NO_AUTH=false
MCP_ALLOW_SHELL=true
RATE_LIMIT_PER_MINUTE=120
# 将您的静态 ngrok 域名粘贴在此处。仅使用域名，不包括 https://
NGROK_DOMAIN=您的域名.ngrok-free.dev
```
使用以下命令生成令牌：
```bash
python3 - <<'PY'
import secrets
print(secrets.token_urlsafe(48))
PY
```
## 启动、停止、重启和状态
在 `pip install -e .` 之后，`mac-mcp` 命令在虚拟环境中可用：
```bash
mac-mcp start # 仅本地服务器
mac-mcp start --ngrok # 本地服务器 + ngrok 隧道
mac-mcp status
mac-mcp restart --ngrok
mac-mcp stop
```
有用选项：
```bash
mac-mcp start --host 127.0.0.1 --port 8000
mac-mcp start --ngrok --ngrok-domain 您的域名.ngrok-free.dev
mac-mcp start --reload
mac-mcp stop --force
```
`mac-mcp start` 仅在 `127.0.0.1:8000` 上启动本地服务器。`mac-mcp start --ngrok` 在后台启动本地服务器和托管的 ngrok 隧道。
日志写入到：
```text
~/.mac-mcp/mac-mcp.log
```
您也可以直接运行服务器：
```bash
uvicorn mcp_server.main:app --host 127.0.0.1 --port 8000
```
## 本地端点
服务器暴露：
```text
MCP: http://127.0.0.1:8000/mcp
REST: http://127.0.0.1:8000/api/*
```
示例 REST 请求：
```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 '{}'
```
示例命令请求：
```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}'
```
## 获取静态 ngrok 开发域名
Custom GPT 操作需要一个公共的 HTTPS URL。对于本地开发，ngrok 是最简单的选择。
1. 登录或创建 ngrok 账户。
2. 安装并验证 ngrok：
```bash
ngrok config add-authtoken 您的 NGROK_AUTHTOKEN
```
3. 在 ngrok 仪表板中创建静态域名：
```text
Cloud Edge / Domains -> 新域名
```
您将获得一个类似的域名：
```text
您的域名.ngrok-free.dev
```
4. 将静态域名粘贴到 `mcp_server/.env` 中：
```env
NGROK_DOMAIN=您的域名.ngrok-free.dev
```
仅使用域名。不要在 `NGROK_DOMAIN` 中包含 `https://`。
5. 同时启动 Mac MCP 和 ngrok：
```bash
mac-mcp start --ngrok
```
这在 `http://127.0.0.1:8000` 上启动本地服务器，在：
```text
https://您的域名.ngrok-free.dev
```
您也可以从命令行覆盖域名：
```bash
mac-mcp start --ngrok --ngrok-domain 您的域名.ngrok-free.dev
```
## Custom GPT 操作设置
使用附带的 OpenAPI 文件：
```text
openapi/custom-gpt-actions.json
```
在将其导入 GPT 构建器之前，请替换占位符服务器 URL：
```json
"servers": [
{
"url": "https://您的静态-ngrok-域名.ngrok-free.dev"
}
]
```
替换为您的 ngrok 域名：
```json
"servers": [
{
"url": "https://您的域名.ngrok-free.dev"
}
]
```
在 GPT 构建器中：
1. 打开您的 GPT。
2. 转到 配置 -> 操作。
3. 创建新的操作。
4. 导入 `openapi/custom-gpt-actions.json`。
5. 根据 UI 设置身份验证为 API 密钥或 Bearer 令牌。
6. 使用此头部格式：
```text
Authorization: Bearer 您的 MCP_API_KEY
```
REST 端点都在 `/api` 下，操作 ID 是稳定的。例如：
```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 格式
Custom GPT 操作模式需要三个主要部分：
```json
{
"openapi": "3.1.1",
"info": {
"title": "Mac MCP 服务器",
"version": "1.0.0"
},
"servers": [
{
"url": "https://您的域名.ngrok-free.dev"
}
],
"paths": {
"/api/system_info": {
"post": {
"operationId": "get_system_info",
"summary": "获取 macOS 系统信息",
"responses": {
"200": {
"description": "成功响应。"
}
}
}
}
}
}
```
对于 `/api/files`、`/api/macos`、`/api/browser` 和 `/api/search` 等分组端点，`tool` 字段选择内部操作。示例：
```json
{
"tool": "read_file",
"path": "~/Desktop/example.txt"
}
```
浏览器示例：
```json
{
"tool": "browser_open_url",
"browser": "Google Chrome",
"url": "https://example.com",
"new_tab": true
}
```
## MCP 端点
支持通过可流式 HTTP 的客户端可以连接到：
```text
https://您的域名.ngrok-free.dev/mcp
```
如果启用身份验证，请使用相同的 Bearer 令牌。
## 安全建议
- 使用 ngrok 时，请保持 `MCP_ALLOW_NO_AUTH=false`。
- 使用长随机 `MCP_API_KEY`。
- 优先使用 `127.0.0.1` 作为本地绑定地址。
- 不要提交 `.env`、日志、作业输出、截图或个人文件。
- 审查您向 AI 客户端公开的每个工具。Shell、文件、浏览器和 AppleScript 工具非常强大。
- 在不使用时停止服务器和托管的 ngrok 隧道：
```bash
mac-mcp stop
```
## 仓库结构
```text
mcp_server/ Python 服务器和工具实现
openapi/custom-gpt-actions.json
pyproject.toml 包元数据和 mac-mcp CLI 入口点
README.md
```
## 许可证
MIT
