Connect your assistant.
Choose the app you use. Every connection reaches the same hosted Relay; setup depends on the client.
Choose a connection guide
https://applemailrelay.xyz/mcpClaude · desktop & web
Add a remote connector in Claude or Claude Desktop. The terminal version, Claude Code, has its own setup below.
- Open Customize → Connectors. Older versions put Connectors under Settings.
- Choose + Add → Add custom connector. Name it AppleMail Relay and paste the MCP server URL shown above, including /mcp.
- Continue through authentication. Choose Sign in now. If an OAuth client choice appears, select Register automatically; this relay supports automatic registration.
- Finish adding the connector, choose Connect if prompted, sign in to AppleMail Relay, and approve the permissions you want.
- Enable the connector in your conversation’s tools menu, then try the read-only check below.
On Team or Enterprise, an owner may need to add the connector in Organization settings → Connectors → Add → Custom → Web first. Members then connect their own account. Availability depends on your Claude plan and organization settings.
Claude connector setupUse an API key instead
- Sign in to your dashboard, open Agent connections, and create a named API key. Save it when it is shown.
- Choose bearer-token authentication in your agent. In a token field, paste only the key. In custom headers, use the header below.
- Save and reload the agent’s tools. Revoke the key in the dashboard when you no longer need it.
Authorization: Bearer YOUR_RELAY_API_KEY
Use a Relay API key here. Your Apple app-specific password belongs only in your Relay service settings. Keep keys in your client’s secret store or private user configuration.
Example JSON configuration
For clients that accept mcpServers, url, and headers. Merge this into your existing configuration and replace the placeholder privately. Match your client’s schema: Gemini uses httpUrl, Codex uses TOML, and Hermes uses mcp_servers in YAML.
{
"mcpServers": {
"applemail-relay": {
"url": "https://applemailrelay.xyz/mcp",
"headers": {
"Authorization": "Bearer YOUR_RELAY_API_KEY"
}
}
}
}Check the connection or fix missing tools
After authorizing, confirm the server shows tools, then try this if you enabled Mail read access:
Use AppleMail Relay to list my mail folders. Do not read message contents, send messages, or change anything.
For Calendar-only, Reminders-only, or Notes-only accounts, ask the agent to list your calendars, reminder lists, or note folders instead. Reminders and Notes need the Mac companion online.
A saved server or unused key does not complete the dashboard checklist. It updates after the agent first makes an authenticated request. If access fails, check email confirmation, your active plan, and service permissions.
When you enable more permissions, authorize the connection again or issue a new key. Refresh the client’s tools afterward. A 401 before OAuth sign-in is expected; opening /mcp as a normal web page does not test the connection. Choose Streamable HTTP, with the complete /mcp path.
Connector icon
The server publishes a Relay icon for clients that read MCP icon metadata. If your app has its own icon field, use this public PNG or upload the downloaded file.
https://applemailrelay.xyz/icon.pngSome apps keep their own catalog artwork or cached icons. Refreshing the connection may help; the client controls whether the icon appears.
Instructions checked 16 November 2026. Client versions and organization policies can change the available controls.