apple-mcp-http

HTTP wrapper for apple-mcp server, providing MCP Streamable HTTP transport on top of the existing stdio implementation.

Overview

HTTP wrapper for apple-mcp server, enabling remote access via HTTP/HTTPS transport. Use Tailscale to securely access your Mac's Apple apps from other computers with automatic HTTPS (required for Claude Code).

Features

• ✅ MCP Streamable HTTP transport (spec version 2025-06-18)
• ✅ Multiple concurrent client connections
• ✅ Server-Sent Events (SSE) streaming
• ✅ Secure session management
• ✅ DNS rebinding attack prevention
• ✅ Easy upstream updates via git submodule

Architecture

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

Quick Start

# 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://<hostname>.<tailnet>.ts.net URL

Installation

# 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

Updating apple-mcp Submodule

To pull in the latest changes from upstream apple-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"

Development

# 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

Configuration

Environment variables:

• PORT - HTTP server port (default: 3000)
• HOST - Bind address (default: 127.0.0.1)
• NODE_ENV - Environment (development/production)

Remote Access

Tailscale HTTPS Setup

Tailscale provides secure HTTPS access for remote computers, required for Claude Code and recommended for any remote access.

On server Mac:

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

On client computer: Use the HTTPS URL in MCP clients. Claude Code example:

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

Benefits:

• Secure remote access across your Tailscale network
• Automatic HTTPS with valid certificates (required for Claude Code)
• No port forwarding or firewall configuration
• Stable URL persists across restarts

API Endpoints

POST /mcp

Main MCP JSON-RPC endpoint. Accepts JSON-RPC requests and returns responses.

Headers:

• Content-Type: application/json (required)
• MCP-Protocol-Version: 2025-06-18 (required)
• Mcp-Session-Id: <uuid> (required after initialization)

Request Example:

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

Response:

• Status: 200 OK for requests
• Status: 202 Accepted for notifications
• Header: Mcp-Session-Id (returned on initialize)

GET /mcp

Opens SSE stream for server-initiated messages.

Headers:

• Accept: text/event-stream (required)
• Mcp-Session-Id: <uuid> (required)

Response:

• Status: 200 OK
• Content-Type: text/event-stream
• Stream of JSON-RPC messages as SSE events

GET /health

Health check endpoint showing server status.

Response Example:

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

DELETE /mcp

Terminate session and clean up resources.

Headers:

• Mcp-Session-Id: <uuid> (required)

Response:

{
  "success": true
}

Usage Examples

Basic MCP Client Flow

1. Initialize Session:

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
  }'

Save the Mcp-Session-Id from the response header.

2. List Available Tools:

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

3. Call a Tool:

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

4. Open SSE Stream (optional):

curl -N http://localhost:3000/mcp \
  -H "Accept: text/event-stream" \
  -H "Mcp-Session-Id: <your-session-id>"

5. Terminate Session:

curl -X DELETE http://localhost:3000/mcp \
  -H "Mcp-Session-Id: <your-session-id>"

Using with Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

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

Then restart Claude Desktop. The apple-mcp tools will be available in conversations.

Security

• Origin header validation (localhost only)
• Server bound to 127.0.0.1 (not exposed to network)
• Secure session IDs (UUID v4)
• Rate limiting (100 requests / 15 minutes)
• HTTPS recommended for production

Project Structure

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

License

MIT

Credits

• Built on top of apple-mcp by Dhravya Shah
• Uses Model Context Protocol by Anthropic