Apple MCP HTTP

苹果mcp http

苹果mcp服务器的HTTP包装器，在现有stdio实现的基础上提供mcp流式HTTP传输。

概述

苹果mcp服务器的HTTP包装器，支持通过HTTP/HTTPS传输进行远程访问。使用Tailscale通过自动HTTPS（Claude Code需要）从其他计算机安全访问Mac的Apple应用程序。

特性

• ✅ MCP流式HTTP传输（规范版本2025-06-18）
• ✅ 多个并发客户端连接
• ✅ 服务器发送事件（SSE）流
• ✅ 安全会话管理
• ✅ DNS重新绑定攻击防御
• ✅ 通过git子模块轻松进行上游更新

建筑

HTTP Client → POST /mcp → Session Manager → Message Router → Stdio Bridge
                                                                    ↓
                                                              apple-mcp (submodule)
                                                                    ↓
                                                            stdout responses
                                                                    ↓
SSE/JSON Response ← HTTP Client ← Message Router ← Stdio Bridge

快速开始

# Clone and install
git clone --recursive https://github.com/natesena/apple-mcp-http.git
cd apple-mcp-http
bun install

# Start server
bun run dev

# Enable HTTPS via Tailscale (for remote access)
tailscale funnel --bg 3001
tailscale serve status  # Get your https://..ts.net URL

安装

# Clone with submodule
git clone --recursive https://github.com/natesena/apple-mcp-http.git
cd apple-mcp-http

# Install dependencies
bun install

# Start development server
bun run dev

更新苹果mcp子模块

要获取上游苹果mcp的最新变化：

# Update submodule to latest main branch
git submodule update --remote apple-mcp

# Commit the update
git add apple-mcp
git commit -m "Update apple-mcp to latest version"

发展

# Start development server with hot reload
bun run dev

# Run tests
bun test tests/integration/http-server.test.ts

# Build for production
bun run build

# Start production server
bun run start

配置

环境变量：

• PORT -HTTP服务器端口（默认值：3000）
• HOST -绑定地址（默认值：127.0.0.1）
• NODE_ENV -环境（开发/生产）

远程访问

Tailscale HTTPS设置

Tailscale为远程计算机提供安全的HTTPS访问，这是Claude Code所必需的，建议用于任何远程访问。

在Mac服务器上：

tailscale funnel --bg 3001
tailscale serve status  # Note your URL

在客户端计算机上： 在MCP客户端中使用HTTPS URL。Claude代码示例：

{
  "mcpServers": {
    "apple-mcp-http": {
      "url": "https://..ts.net/mcp",
      "transport": { "type": "http" }
    }
  }
}

优点：

• 通过您的Tailscale网络进行安全的远程访问
• 带有效证书的自动HTTPS（Claude Code需要）
• 无端口转发或防火墙配置
• 重新启动后URL保持稳定

API终点

POST/mcp

主MCP JSON-RPC端点。接受JSON-RPC请求并返回响应。

标题：

• Content-Type: application/json （必填）
• MCP-Protocol-Version: 2025-06-18 （必填）
• Mcp-Session-Id: （初始化后需要）

请求示例：

{
  "jsonrpc": "2.0",
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": {
      "name": "my-client",
      "version": "1.0.0"
    }
  },
  "id": 1
}

答复：

• 状态： 200 OK 对于请求
• 状态： 202 Accepted 用于通知
• 头球 Mcp-Session-Id （初始化时返回）

GET/mcp

为服务器启动的消息打开SSE流。

标题：

• Accept: text/event-stream （必填）
• Mcp-Session-Id: （必填）

答复：

• 状态： 200 OK
• 内容类型： text/event-stream
• JSON-RPC消息流作为SSE事件

GET/健康

显示服务器状态的健康检查端点。

响应示例：

{
  "status": "ok",
  "sessions": 2,
  "pendingRequests": 0,
  "bridgeStatus": "running"
}

删除/mcp

终止会话并清理资源。

标题：

• Mcp-Session-Id: （必填）

答复：

{
  "success": true
}

使用示例

基本MCP客户端流

1. 初始化会话：

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{
    "jsonrpc": "2.0",
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": {"name": "test", "version": "1.0"}
    },
    "id": 1
  }'

保存 Mcp-Session-Id 从响应标头中。

1. 列出可用工具：

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -H "Mcp-Session-Id: " \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "params": {},
    "id": 2
  }'

1. 调用工具：

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -H "Mcp-Session-Id: " \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "get_contacts",
      "arguments": {}
    },
    "id": 3
  }'

1. 打开SSE流（可选）：

curl -N http://localhost:3000/mcp \
  -H "Accept: text/event-stream" \
  -H "Mcp-Session-Id: "

1. 终止会话：

curl -X DELETE http://localhost:3000/mcp \
  -H "Mcp-Session-Id: "

与Claude Desktop一起使用

添加到您的Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "apple-mcp": {
      "url": "http://localhost:3000/mcp",
      "transport": {
        "type": "http"
      }
    }
  }
}

然后重新启动Claude Desktop。苹果mcp工具将在对话中提供。

安全

• 源标头验证（仅限本地主机）
• 服务器绑定到127.0.0.1（未暴露在网络中）
• 安全会话ID（UUID v4）
• 速率限制（100个请求/15分钟）
• HTTPS建议用于生产

项目结构

apple-mcp-http/
├── apple-mcp/              # Git submodule
├── src/
│   ├── index.ts           # HTTP server entry point
│   ├── bridge/            # Stdio bridge to apple-mcp
│   ├── session/           # Session management
│   ├── router/            # Message routing
│   ├── sse/               # SSE streaming
│   ├── middleware/        # Security middleware
│   ├── routes/            # HTTP routes
│   └── utils/             # Utilities
├── tests/
│   ├── unit/
│   └── integration/
└── dist/                   # Build output

许可证

麻省理工学院

鸣谢

• 建在上面 苹果mcp 由Dhravya Shah撰写
• 用途 模型上下文协议 通过Anthropic