Skip to main content
Glama
spare-email-mcp

spare-email-mcp

Official

spare-email-mcp

A read-only Model Context Protocol server for spare.email mailboxes (works with any cloudflare_temp_email deployment).

It lets MCP-aware agents (Claude, Cursor, Codex, ...) look inside a mailbox you already created: list the inbox, read a parsed mail, and wait for a verification code. It is deliberately read-only: it cannot create mailboxes, delete mail, or send anything, and it holds no credentials of its own — it uses the same Address JWT you can copy from the web UI.

Tools

Tool

Purpose

mailbox_info

Returns the mailbox address the server is authenticated as. Use first to verify the JWT works.

list_mails

List recent mails, newest first (limit 1-100, offset).

read_mail

Read one mail in full by id: from/to/subject/date, plain-text body, attachment metadata.

wait_for_otp

Poll until a new mail arrives after the call starts, then extract the most likely verification code. Supports timeout_seconds (10-600), poll_seconds (3-30), and subject_contains filtering.

Code extraction runs locally in the server using the multilingual rule-based extractor ported verbatim from the upstream worker (extract_code.ts, MIT) — keyword-anchored patterns in about a dozen languages, with guards against dates, amounts, phone numbers, and URLs. No AI model and no extra API calls.

No mail arrives within the timeout? wait_for_otp returns a structured "nothing arrived" result instead of hanging or guessing.

Related MCP server: Stalwart Mail MCP

Configuration

The server is configured entirely through environment variables:

Variable

Required

Meaning

SPARE_EMAIL_JWT

yes

Address JWT, copied from the spare.email web UI (settings).

SPARE_EMAIL_BASE_URL

no

API base URL. Defaults to https://spare.email; point it at your own deployment if self-hosting.

SPARE_EMAIL_SITE_PASSWORD

no

Only if the deployment enabled the site-wide access password (x-custom-auth).

SPARE_EMAIL_LANG

no

Error-message language, en (default) or zh.

Every tool reports an actionable error on failure — for example, an expired JWT returns a hint to copy a fresh one from the web UI.

Usage

Claude Code

claude mcp add spare-email -e SPARE_EMAIL_JWT=eyJ... -- node /path/to/spare-email-mcp/dist/index.js

Claude Desktop / Cursor / generic mcpServers block

{
  "mcpServers": {
    "spare-email": {
      "command": "node",
      "args": ["/path/to/spare-email-mcp/dist/index.js"],
      "env": {
        "SPARE_EMAIL_JWT": "eyJ...",
        "SPARE_EMAIL_BASE_URL": "https://spare.email"
      }
    }
  }
}

Security notes

  • The JWT grants full read access to that one mailbox only. Treat it like a password in your MCP config; rotate it by opening a fresh mailbox (or changing its password) in the web UI.

  • The mailbox lifetime rules of the deployment apply: on spare.email a default mailbox auto-expires, so point long-lived agent workflows at a mailbox with the retention you want and keep a copy of its JWT.

  • The server is stateless and never writes: no mailbox creation, no send, no deletes. Rate limits are honored (429 responses back off a poll cycle).

Typical agent workflow

  1. Human creates a mailbox in the web UI and copies the Address JWT into the MCP server config.

  2. Agent signs up somewhere using that mailbox address.

  3. Agent calls wait_for_otp (optionally filtering by subject) and gets the verification code without any human copy-pasting.

Development

npm install
npm run build    # tsc -> dist/
SPARE_EMAIL_JWT=... SPARE_EMAIL_BASE_URL=... npm run smoke

Provenance

Developed as part of the spare.email stack (https://spare.email); this repository is the canonical home of the published package.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      MCP server that gives an agent its own email inbox: it opens the inbox, waits for the one-time code a signup sends, and reads or sends mail. Addresses are permanent, so a test suite does not need a new one per run; only the messages expire, on a retention window you set.
      19
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables authenticated MCP clients to list, search, read, flag, draft, and optionally send mail from one Gmail or Microsoft 365 mailbox using OAuth without app registration.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables software agents to read and manage their own mailboxes, inspect inbound messages, and request outbound email that remains pending until an owner approves it. Exposes these agent mail operations as remote MCP tools alongside a REST API.
      MIT