https://github.com/maximbilan/apple-mail-mcp-go
Go MCP server for Apple Mail on macOS: read, search, send, and organize Mail.app messages.
https://github.com/maximbilan/apple-mail-mcp-go
apple-mail applescript claude-code claude-desktop golang macos mail-app mcp model-context-protocol
Last synced: 22 days ago
JSON representation
Go MCP server for Apple Mail on macOS: read, search, send, and organize Mail.app messages.
- Host: GitHub
- URL: https://github.com/maximbilan/apple-mail-mcp-go
- Owner: maximbilan
- License: mit
- Created: 2026-05-10T07:45:20.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-10T15:15:50.000Z (about 2 months ago)
- Last Synced: 2026-05-10T15:36:39.400Z (about 2 months ago)
- Topics: apple-mail, applescript, claude-code, claude-desktop, golang, macos, mail-app, mcp, model-context-protocol
- Language: Go
- Size: 47.9 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# apple-mail-mcp
[](https://github.com/maximbilan/apple-mail-mcp-go/actions/workflows/ci.yml)
[](https://github.com/maximbilan/apple-mail-mcp-go/releases)
[](https://github.com/maximbilan/apple-mail-mcp-go/blob/main/LICENSE)
`apple-mail-mcp` is a Go Model Context Protocol (MCP) server for macOS that gives MCP-compatible assistants programmatic access to Mail.app for listing accounts/mailboxes, searching and reading messages, sending drafts/emails, and unread-count workflows.
## Prerequisites
- macOS 12+
- Mail.app configured with at least one account
- Go 1.22+ (only required for building from source)
## Installation
### 1. One-click for Claude Desktop
Download `apple-mail-mcp.mcpb` from the [latest release](https://github.com/maximbilan/apple-mail-mcp-go/releases/latest) and double-click it. Claude Desktop installs and registers the server automatically.
### 2. One-line install (recommended for Claude Code or both clients)
```sh
curl -fsSL https://raw.githubusercontent.com/maximbilan/apple-mail-mcp-go/main/install.sh | sh
```
This installer:
- Detects macOS architecture and installs `~/.local/bin/apple-mail-mcp`
- Uses local `go build`/`go install` when Go exists, otherwise downloads the latest release binary and verifies SHA256
- Detects Claude Desktop and/or Claude Code and offers registration
### 3. Build from source (Go developers)
```sh
go install github.com/maximbilan/apple-mail-mcp-go/cmd/apple-mail-mcp@latest
apple-mail-mcp install
```
### 4. Manual configuration
Claude Desktop config path:
`~/Library/Application Support/Claude/claude_desktop_config.json`
Add/update:
```json
{
"mcpServers": {
"apple-mail": {
"command": "/Users//.local/bin/apple-mail-mcp",
"args": []
}
}
}
```
Claude Code:
```sh
claude mcp add apple-mail "$HOME/.local/bin/apple-mail-mcp" --scope user
```
## Permissions
The first time `osascript` controls Mail.app, macOS shows an Automation permission prompt.
Grant access for the calling process (for example Terminal, Claude Desktop, or Claude Code).
If needed, manage this at:
`System Settings -> Privacy & Security -> Automation`
## Tool Reference
Generated from registered tools via:
```sh
go run ./cmd/apple-mail-mcp tools-docs
```
| Name | Params | Description |
|---|---|---|
| list_accounts | none | List account names configured in Mail.app. |
| list_mailboxes | account (string, required) | List mailboxes for an account with unread counts. |
| search_messages | account (required), mailbox, sender_contains, subject_contains, unread_only, date_from, date_to, limit | Search messages with server-side filters. |
| get_message | message_id (required), include_body | Get message metadata and optionally full body. |
| get_unread_count | account (optional) | Get total and per-mailbox unread counts. |
| send_email | to, subject, body, cc, bcc, account | Send a plaintext email immediately. |
| create_draft | to, subject, body, cc, bcc, account | Create a draft email without sending. |
| mark_as_read | message_ids, read | Mark messages as read/unread (max 100 ids). |
## Running
Start over stdio transport:
```sh
apple-mail-mcp --log-level info
```
Read-only mode (write tools hidden):
```sh
apple-mail-mcp --read-only
```
## Known Limitations
- Some Mail messages can have missing/malformed date metadata. `search_messages` falls back from `date sent` to `date received`, and date can be empty when unavailable.
- Gmail label model can surface `All Mail` semantics. `search_messages` mailbox output reflects the mailbox requested in the query (for example `INBOX`) to avoid confusion.
## Integration Tests
Integration tests require Mail.app on macOS and explicit build tag:
```sh
go test ./tests/integration -tags=integration -v
```
## Troubleshooting
- Mail.app not responding:
- Open Mail.app once and ensure account sync completes.
- Permission denied:
- Re-check macOS Automation permissions for the process invoking the server.
- AppleScript timeout:
- Open Mail.app, wait for sync to settle, then retry.
- Increase timeout with `APPLE_MAIL_MCP_TIMEOUT` (e.g. `120s` or `180`).
- Config did not update:
- Restart Claude Desktop and run `claude mcp list` for Claude Code.
## Release Validation Checklist
Before creating a public release:
```sh
go build ./...
go vet ./...
go test ./... -race
```
Install path smoke checks:
```sh
./install.sh
apple-mail-mcp install --yes
apple-mail-mcp uninstall --yes
```
## Uninstall
```sh
./uninstall.sh
```
Or if installed from `go install`:
```sh
apple-mail-mcp uninstall
```
## License
MIT