Oppen Apple Bridge

English | 简体中文

Turn a conversation into a reminder, a calendar event, or a note on your Mac.

After talking something through with an AI assistant, you usually still have to open another app and type it all in again. Oppen Apple Bridge connects that last step: a remote MCP client can ask your Mac to create the item through an Apple Shortcut.

Once connected, you can ask things like:

Remind me tomorrow at 3 pm to submit the funding application. Add a note to bring the printed form.

Put our team meeting on Friday from 2 to 3 pm, in meeting room A.

Save the points we just discussed as a note called “Meeting prep.”

Your assistant interprets the request and calls a tool. The bridge handles the local app. There is no model bundled with this project. Tunnel mode needs an OpenAI runtime key for tunnel access, not for running a model.

v0.3.1 · macOS · Python 3.13+ · MIT

Get started · Tools · Deployment guide (中文)

Create a list and a reminder from one request. Waiting time is sped up.

What it does

By default, items go into a list, calendar, or folder named Oppen Apple Bridge. You can choose another destination in each tool call. Your system default list is not changed.

This release only creates items. Searching, editing, completing, and deleting existing records are not implemented yet. Calendar events do not support all-day events, recurrence, or invitations; notes do not support attachments.

Apple's Urgent reminder property is not supported. High priority is not a substitute, and the tool does not expose an urgent parameter. A Reminders list holds reminders; creating a group of lists is also outside the current tools.

Related MCP server: apple-mcp

How it works

ChatGPT → OpenAI Secure MCP Tunnel → private stdio bridge
                 OR
Remote MCP client → HTTPS + OAuth → loopback Python service
    ↓ shortcuts CLI, with JSON over stdin
Oppen Apple Bridge Shortcut
    ↓ macOS application scripting interfaces
Reminders / Calendar / Notes

The service handles authentication, permissions, and input validation. The Shortcut handles Apple apps. It does not simulate mouse clicks or keystrokes, and user input is never assembled into a shell command.

This is a single-owner service for a Mac you control. The Mac must be awake, online, and logged in. Reminders and Notes use iCloud; Calendar uses the writable calendar you choose. It is not a Linux-hosted service or a multi-user account system.

Get started

New in v0.3.1: OpenAI Secure MCP Tunnel and a guided Mac installer. You do not need FRP, your own domain, or a public server for this mode.

Before installing, check that you can access OpenAI Platform → Tunnels. You need a Tunnel ID and a runtime API key with Tunnels Read + Use permissions. Account/workspace availability is controlled by OpenAI; a ChatGPT subscription alone is not a guarantee of access. Do not use an admin key for the running service.

Download and install

Download for Mac — complete installation package

1. Unzip the download and move the whole folder to a permanent location.

2. Double-click Install.command.

3. Follow the prompts. The Shortcut is already included; nothing else needs downloading separately.

If macOS blocks double-clicking, open Terminal in the extracted folder and run bash Install.command. The installer is not a notarized Mac app.

The installer checks the packaged files, installs Homebrew if needed, installs Python and the official tunnel-client, prepares the Python environment, opens the signed Shortcut, and starts a dedicated login service. It asks you to:

1. Import Oppen Apple Bridge and approve macOS first-use permissions. There are no actions to assemble.

2. Enter your Tunnel ID and runtime key (hidden input, saved locally with 0600 permissions).

3. Choose whether to enable Calendar and Notes. Reminders and list creation are enabled by default.

4. Select the tunnel in ChatGPT connector settings, after the installer reports ready: true.

This is guided installation, not zero-interaction setup: OpenAI account setup and Apple's import/permission dialogs still need you. The Mac must remain awake, online, and logged in.

Tunnel authentication: the local bridge uses a private stdio pipe, not an HTTP port. OpenAI tunnel permissions control access; select None for additional MCP authentication in this mode. There is no bridge-password page. Anyone you grant access to this tunnel can use the capabilities enabled in its local configuration. Never share it more broadly than intended.

Try: “Create a Reminders list called Funding Application, then remind me in 10 minutes to submit the form in that list.” Calendar and Notes destinations must already exist if those capabilities are enabled.

Existing HTTPS / FRP users

Your existing setup still uses the password-protected OAuth flow. Follow HTTPS setup; you do not need to switch to Tunnel. The installer does not modify FRP configuration. Do not run a second copy of the same tunnel ID during an upgrade.

See Tunnel setup and troubleshooting for restart, logs, upgrades, and account requirements.

Tools

Use ISO 8601 timestamps with seconds and an explicit time zone, such as 2027-01-15T15:00:00+08:00. An event's end must be later than its start. Note bodies are plain text: line breaks are preserved, and HTML-like text is escaped.

Example arguments for apple_create_reminder:

{
  "title": "Submit funding application",
  "due_at": "2027-01-15T15:00:00+08:00",
  "notes": "Bring the printed form",
  "list": "Oppen Apple Bridge"
}

Keep it running

For Tunnel mode: .venv/bin/python tunnel.py status, restart, stop, or logs. Use configure followed by install to change the tunnel key or capabilities.

The commands below apply to HTTPS / OAuth mode.

After checking the foreground service, stop it with Ctrl+C and install the LaunchAgent:

.venv/bin/python service.py install

It starts at user login and restarts if the process exits.

.venv/bin/python service.py status
.venv/bin/python service.py restart
.venv/bin/python service.py logs

Change APPLE_BRIDGE_PASSWORD in .env, then restart to apply it. Passwords may contain 1–256 characters and cannot be empty or contain newlines or NUL. Quote values containing spaces or #. Changing the password revokes existing grants; restarting with the same password preserves them.

Logs live in .runtime/server.log, .runtime/launchd.log, and .runtime/launchd-error.log. Stop the old service before moving the checkout. See the deployment guide (中文) for service removal and troubleshooting.

Data and permissions

The bridge uses the Apple apps already signed in on your Mac. It does not collect Apple ID credentials. OAuth grants separate permissions for reminders, lists, calendar events, and notes.

Request content passes through your chosen AI client as well as your Mac, so this is not an entirely local data flow. Routine server logs omit titles, bodies, and credentials. Live verification scripts save their test results under .runtime/.

A timed-out creation may still have succeeded. Check the app before retrying; another call can create a duplicate.

Contributing

See CONTRIBUTING.md for the development workflow and the changelog for release notes.

Bug reports with a macOS version, tool name, sanitized arguments, and the actual error are useful. Please leave passwords, the OAuth database, and private note content out of issues and attachments.

Run the tests with:

.venv/bin/python -m pytest -q

They cover input validation, OAuth, password changes, scope isolation, and Shortcut input handling. Live scripts can also create and read back real records; those are separate checks, described in the deployment guide.

A few places to start:

If you change the Shortcut script, rebuild, validate, sign, and import the resulting file. Updating the Python service alone does not update an imported Shortcut.

License and acknowledgments

MIT. The OAuth implementation builds on OppenSteward-MCP's single-owner design and retains its license notice. Shortcut building, validation, and signing use Shortcuts Playground.

The documentation takes cues from apple-mcp, Apple Events MCP Server, and the MCP Feature Reference Server. They are also worth exploring for other approaches to Apple apps and remote MCP.