fastmail

The Fastmail MCP Server exposes a small MCP interface to access a Fastmail inbox via JMAP. It provides three tools: list_inbox_emails, which lists emails in the Inbox with fields like id, sender, subject, and date; query_emails_by_keyword, which searches emails by a keyword in the subject or body while ignoring junk and deleted messages and returns total matches plus a paginated page; and get_email_content, which fetches the content of a specific email by id and converts HTML content to text. To use the server, you must supply a bearer token via the BEARER_TOKEN environment variable when starting the server, and when calling the tools you must include a Fastmail API token in the request headers (fastmail-api-token). Clients can interact with the server using the FastMCP client, calling the tool names (e.g., list_inbox_emails) through a transport configured to point at http://<host>:8000/mcp/ with the Bearer token and the Fastmail API token included in headers. The server runs locally by default at http://127.0.0.1:8000/mcp/ but it can be exposed via tunneling or reverse proxies as needed for OpenAI integration.

Prerequisites:

• Python 3.12+ installed on your system
• Virtual environment support (recommended)
• Access to the repository (git)

Install and run locally:

# Clone the repository
git clone https://github.com/jeffjjohnston/fastmail-mcp-server.git
cd fastmail-mcp-server

# Create and activate a virtual environment
python3.12 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Configure and run:

# Set required environment variable for authorization
export BEARER_TOKEN="your-static-token"

# Optional: set log level
export LOG_LEVEL="DEBUG"  # or INFO

# Run the server
python server.py

Notes:

• The server listens by default on http://127.0.0.1:8000/mcp/
• Ensure your Fastmail API token is managed by the MCP client as a header named fastmail-api-token when invoking tools.
• If running behind a firewall or via a tunnel, expose port 8000 accordingly and adjust client URLs.

Tips and caveats:

• BEARER_TOKEN is required to authorize HTTP requests to the MCP server; keep it secret.
• The Fastmail API token is not stored on the server; it must be provided by MCP clients in request headers (fastmail-api-token).
• If LOG_LEVEL is not set, the server defaults to INFO; use DEBUG while debugging.
• Ensure Python 3.12 compatibility and that the virtual environment uses Python 3.12 executables.
• When testing locally, you can use pytest to run the test suite as described in the README.
• If you need to expose the server publicly for OpenAI remote MCP, consider using a secure tunnel (e.g., Cloudflare tunnel) and update the server_url in the OpenAI tool configuration accordingly.