FA
SearchCommunicationProductivity

Fastmail MCP Server: JMAP Email, Contacts, Calendar

Access Fastmail via the MCP server to list and search email, send and move mail, manage attachments and threads, plus contacts and calendar.

View on GitHub
Quick Install
npx -y @MadLlama25/fastmail-mcp

Overview

The Fastmail MCP Server is a small bridge that lets developers access Fastmail data (email, contacts, calendar) through a Model Context Protocol (MCP) endpoint backed by Fastmail’s JMAP API. It exposes common mail operations — listing and searching messages, sending and moving mail, managing attachments and threads — alongside basic contact and calendar access. The server is intended for integrations that prefer a consolidated, protocol-oriented interface rather than directly implementing JMAP.

By running the MCP server you get a single local or network-accessible service that translates MCP-style requests into JMAP calls against a Fastmail account. This simplifies building tooling, search/indexing pipelines, or automation agents that need to operate on email, contacts, and events without dealing with JMAP details in each consumer.

Features

  • List mailboxes, threads, and individual messages
  • Full-text search and targeted message queries
  • Send email, including attachments
  • Move messages between mailboxes (folders)
  • Fetch and stream attachments
  • Manage threads and message flags (read/unread, starred)
  • Access and modify contacts
  • Read calendar events and basic calendar operations
  • Authentication via Fastmail API token or account credentials (configurable)
  • Lightweight server aimed at easy local or container deployment

Installation / Configuration

Basic steps to get the server running locally:

  1. Clone the repository:
git clone https://github.com/MadLlama25/fastmail-mcp.git
cd fastmail-mcp
  1. Build and run (generic build + run; replace with the language/toolchain appropriate for the repo):
# Example: build a binary (if the repo uses Go/Rust/Node, run the corresponding build)
make build
./fastmail-mcp --config config.yaml
  1. Or use Docker:
# Build a local image
docker build -t fastmail-mcp .

# Run with environment variables or an external config file
docker run -d \
  -p 8080:8080 \
  -v $(pwd)/config.yaml:/app/config.yaml:ro \
  --name fastmail-mcp \
  fastmail-mcp

Example configuration (config.yaml):

server:
  listen: "0.0.0.0:8080"
fastmail:
  # Provide a Fastmail API token or username/password depending on supported auth
  api_token: "YOUR_FASTMAIL_API_TOKEN"
  jmap_url: "https://api.fastmail.com/jmap/"
logging:
  level: "info"

Environment variables can typically be used instead of a config file:

  • FASTMAIL_API_TOKEN
  • FASTMAIL_JMAP_URL
  • MCP_LISTEN (e.g. 0.0.0.0:8080)

After launching, the MCP server will listen on the configured port and accept MCP-style requests from clients.

Available Resources

  • Repository: https://github.com/MadLlama25/fastmail-mcp
  • Fastmail JMAP docs: https://www.fastmail.help/hc/en-us/sections/360005767573-JMAP
  • JMAP specification (RFC and community resources)
  • MCP-related documentation and examples (in-repo examples or client adapters, if included)

Check the repository’s README and examples directory for concrete request/response illustrations and any client libraries or CLI helpers bundled with the server.

Use Cases

  • Email search and indexing

    • Run a local indexing pipeline that queries the MCP server for messages matching a search query (e.g., unread messages mentioning a project), fetch message bodies and attachments, and build a search index or knowledge base.
    • Example: request all messages in INBOX with keywords “invoice”, then download attachments for OCR.

  • Automation & bots

    • Build an automation agent that moves messages into project-specific folders when certain conditions match, or that sends templated replies using the MCP server send endpoint.
    • Example: when an incoming message is identified as support, call the MCP send API to confirm receipt and move the original into a support folder.

  • Contact and calendar integrations

    • Sync Fastmail contacts and events into a CRM or calendar aggregator by periodically fetching contacts and upcoming calendar events through the MCP interface.
    • Example: fetch all contacts tagged “sales” and upsert them into an external contacts database.

  • Secure local proxy for JMAP

    • Use the MCP server as a controlled gateway for third-party tools, centralizing API tokens and reducing the number of systems with direct Fastmail credentials.

Quick Examples

Note: exact endpoints may vary depending on the server release. Consult the repo for the request contract.

  • List messages (pseudo-cURL):
curl -X POST http://localhost:8080/mcp/messages/list \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -d '{"mailbox":"INBOX","limit":50,"offset":0}'
  • Search messages:
curl -X POST http://localhost:8080/mcp/messages/search \
  -d '{"query":"from:[email protected] subject:invoice","limit":20}'
  • Send a message with an attachment (multipart/form-data or instruct the server to fetch from a provided URL):
curl -X POST http://localhost:8080/mcp/messages/send \
  -F "[email protected]" \
  -F "subject=Test" \
  -F "body=Hello from MCP" \
  -F "attachment=@/path/to/file.pdf"

Tips

  • Use an API token with limited scope when possible and store it in environment variables or a secrets manager.
  • If you plan to run the server in production, put it behind TLS and restrict access to trusted clients.
  • Inspect the repo’s examples directory (if present) for language-specific client snippets that demonstrate the server’s expected request/response formats.

For full details and up-to-date instructions, see the project’s GitHub repository: https://github.com/MadLlama25/fastmail-mcp.

Tags:communicationproductivitysearch