home / mcp / jxa mail mcp server

JXA Mail MCP Server

Provides fast MCP endpoints to manage Apple Mail data through batch JXA scripts for accounts, mailboxes, and emails.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "imdinu-jxa-mail-mcp": {
      "command": "jxa-mail-mcp",
      "args": [],
      "env": {
        "JXA_MAIL_DEFAULT_ACCOUNT": "Work",
        "JXA_MAIL_DEFAULT_MAILBOX": "Inbox"
      }
    }
  }
}

You can run the JXA Mail MCP server to query and manage your Apple Mail data via a fast, script-driven MCP interface. This server uses JavaScript for Automation and batch property fetching to speed up common mailbox operations, enabling you to list accounts and mailboxes, fetch emails with pagination or filters, and perform fuzzy searches.

How to use

You interact with this MCP server through an MCP client by configuring one or more server entries that point to the running MCP process. The server exposes common mail-related endpoints such as listing accounts, listing mailboxes, fetching emails, and performing both exact and fuzzy searches. You can run the server directly or reference it from another tool or integration that supports MCP servers.

Typical usage patterns include starting the server locally and then querying for data using the MCP client’s endpoints. If you operate from a client or integration, you can set a default account and mailbox to streamline frequent queries, so you don’t need to specify them on every request.

How to install

Prerequisites you need before installing: Python 3.13 or newer, and the UV tooling for running MCP sources. You may also install the MCP server via a package-safe workflow if you prefer a package-oriented setup.

Install with a Python package manager (recommended): you can install the MCP server using a package-scoped installer that handles packaging and execution.

Install from source: clone the repository, install dependencies, and synchronize the development environment with the package manager.

Additional sections

Configuration for default account and mailbox lets you tailor the server to your environment. You can set environment variables to predefine the account and mailbox used by queries. These values can be overridden per client by passing explicit parameters when you query.

Examples of common tasks you can perform with the server include listing all accounts, listing mailboxes for a given account, fetching emails from a mailbox with pagination, fetching today’s emails, fetching unread or flagged emails, and performing both standard and fuzzy searches by subject or sender.

Troubleshooting tips: ensure the MCP server is running when you query, verify that the environment variables are set correctly for default account and mailbox, and check that the client you use is configured to communicate with the MCP server using the correct command and arguments.

Configuration details

{
  "mcpServers": {
    "mail": {
      "command": "jxa-mail-mcp",
      "args": [],
      "env": {
        "JXA_MAIL_DEFAULT_ACCOUNT": "Work",
        "JXA_MAIL_DEFAULT_MAILBOX": "Inbox"
      }
    }
  }
}

Available tools

list_accounts

List all configured email accounts available in Apple Mail.

list_mailboxes

List all mailboxes for a given account.

get_emails

Fetch emails from a specific mailbox with support for pagination.

get_todays_emails

Fetch all emails that arrived today.

get_unread_emails

Fetch all unread emails.

get_flagged_emails

Fetch all emails marked as flagged.

search_emails

Search emails by subject or sender.

fuzzy_search_emails

Perform typo-tolerant searches using trigram and Levenshtein matching.