Skip to main content
Glama
beeltec

mailmcp

by beeltec
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

mailmcp

A local MCP server that controls Apple Mail through JavaScript for Automation. It uses the accounts that are already configured in Mail. It does not need passwords.

Requirements

  • macOS with Apple Mail configured

  • Node.js 22 or later

  • Automation permission to control Mail

  • Accessibility permission, only for delete_mailbox

Related MCP server: Mailbridge for Apple Mail

Install

npm install -g @beeltec/mailmcp
mailmcp setup

Setup lets you select:

  1. The accounts the server can access

  2. The Trash mailbox of each account (detected automatically when possible)

  3. The tools the server offers (destructive tools are off by default)

  4. The harnesses to install the server in: Claude Code, Codex, Cursor, Gemini CLI, opencode, and pi

Run mailmcp setup again to change these settings. Restart the harness after changes.

To add the server manually:

codex mcp add mail -- /absolute/path/to/node /absolute/path/to/mailmcp/dist/cli.js

Configuration

Setup writes ~/.config/mailmcp/config.json. Set MAILMCP_CONFIG to use a different path.

{
  "accounts": [
    { "id": "ACCOUNT-ID-FROM-SETUP", "email": "you@example.com", "trash": ["Trash"] }
  ],
  "tools": ["list_mailboxes", "search_messages", "read_message"]
}

Without tools, all tools are enabled. list_accounts is always enabled. MCP tools cannot change the account allowlist.

Tools

Tools

Purpose

list_accounts, list_mailboxes

List allowed accounts and their mailboxes

get_mailbox, create_mailbox, rename_mailbox, delete_mailbox

Manage custom folders (delete only empty ones)

search_messages, search_mailboxes

Search by subject, sender, recipient, date, and unread state

read_message, read_messages

Read message bodies in pages and list attachments

set_message_state

Set read state or flag color

move_message, trash_message

Move a message within an account or into its Trash

create_draft, reply_to_message, forward_message

Create plain-text drafts

get_draft

Read a draft and get its revision for sending

add_attachment, save_attachment

Attach a local file or save a received attachment to ~/Downloads/mailmcp

send_draft

Send a draft created in this session

Limits

  • Drafts can only be sent from the server session that created them.

  • send_draft needs the current revision from get_draft. Do not retry a timed-out send.

  • Search pages return at most 50 results. Follow nextOffset until it is null.

  • Moves between accounts are not supported.

  • Each request times out after 45 seconds. A timed-out write can still complete in Mail.

Development

npm ci
npm run check
npm run build
npx @modelcontextprotocol/inspector node dist/cli.js

License

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityNo data
ResponsivenessUnresponsive

Resources

Related MCP Connectors

Related MCP Servers

  • MCP Apple Mail

    LionSR
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables integration with Apple Mail on macOS using JavaScript for Automation (JXA). Supports reading, searching, sending, and managing emails across multiple accounts with full mailbox hierarchy support.
    5
    -

  • Apple Mail MCP Server

    LeChabrax
    A
    license
    A
    quality
    B
    maintenance
    Enables AI assistants to read, search, send, and manage email on macOS through programmatic access to Apple Mail.
    29
    MIT

  • che-apple-mail-mcp

    PsychQuant
    A
    license
    Not graded
    quality
    A
    maintenance
    Enables natural-language control of Apple Mail with 53 tools, including millisecond SQLite-powered search across large mailboxes, mailbox and message management, composing and batch operations.
    8
    MIT