MCP Server

Quick Start

Install the Dead Simple Email package with MCP support:

pip install deadsimple-email[mcp]

Claude Desktop

Add the following to your Claude Desktop configuration file. On macOS this is ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows it is %APPDATA%\Claude\claude_desktop_config.json.

{
  "mcpServers": {
    "@deadsimple/email": {
      "command": "python",
      "args": ["-m", "deadsimple.mcp"],
      "env": {
        "DSE_API_KEY": "dse_your_api_key"
      }
    }
  }
}

Restart Claude Desktop and the email tools will appear in the tools menu. You can now ask Claude to create inboxes, send emails, read messages, and more using natural language.

Cursor

Add the same configuration to your Cursor MCP settings. Open Settings → MCP and add a new server, or edit .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "@deadsimple/email": {
      "command": "python",
      "args": ["-m", "deadsimple.mcp"],
      "env": {
        "DSE_API_KEY": "dse_your_api_key"
      }
    }
  }
}

Windsurf

In Windsurf, open Settings → Cascade → MCP and add the server. The configuration file is typically at ~/.windsurf/mcp.json:

{
  "mcpServers": {
    "@deadsimple/email": {
      "command": "python",
      "args": ["-m", "deadsimple.mcp"],
      "env": {
        "DSE_API_KEY": "dse_your_api_key"
      }
    }
  }
}

Hermes Agent

Hermes Agent by Nous Research has first-class MCP support through its YAML config. Add a deadsimple entry to the mcp_servers block in ~/.hermes/config.yaml, then run /reload-mcp in the running Hermes session:

mcp_servers:
  deadsimple:
    command: python
    args: ["-m", "deadsimple.mcp"]
    env:
      DSE_API_KEY: "dse_your_api_key"

For the full walkthrough including a support-triage skill example, see the Hermes Agent integration page.

OpenClaw

OpenClaw reads MCP servers from its mcp_config.json. The OpenClaw integration page has the full walkthrough; the config shape is identical to Claude Desktop's.

Muse Code

Meta's terminal coding agent reads MCP servers from the mcp_servers block of ~/.config/muse/settings.json and supports the streamable_http transport with custom headers, so it connects to the remote server with no local process:

{
  "schema_version": 1,
  "mcp_servers": {
    "deadsimple": {
      "transport": "streamable_http",
      "url": "https://api.deadsimple.email/mcp",
      "headers": { "Authorization": "Bearer dse_your_api_key" }
    }
  }
}

Using the Muse app rather than Muse Code? It does not speak MCP, but it builds its own connectors; the Meta Muse integration page covers that path.

Available Tools

The MCP server exposes 26 tools that cover the full Dead Simple Email API, including the agent calendar, calendar invites and Sign in with Dead Simple. Your AI assistant can call any of these tools when you ask it to work with email.

MCP Events (ChatGPT and dots)

The hosted server speaks MCP 2026-07-28 alongside earlier protocol versions and supports MCP Events, the push mechanism ChatGPT uses to start work in a chat or an OpenAI dot when something changes in a connected app. Instead of polling with wait_for_email, the client subscribes once and new mail is delivered to it. The server advertises an events capability in server/discover and implements events/list, events/subscribe and events/unsubscribe on the same authenticated endpoint as the tools.

Omit inbox_id to watch every inbox on the account. A subscription can only name inboxes the signed-in account owns. Filters are applied on our side, so a non-matching email never reaches the client.

{
  "jsonrpc": "2.0", "id": 2, "method": "events/subscribe",
  "params": {
    "name": "message.received",
    "arguments": { "inbox_id": "<inbox_id>", "from_contains": "@acme.com" },
    "delivery": { "mode": "webhook", "url": "https://receiver.example.com/cb", "secret": "whsec_..." },
    "cursor": null
  }
}

Before a subscription is activated we POST a one-time {"type": "verification", "challenge": "..."} to the callback and require the challenge back. The result carries the subscription id and a refreshBefore time; subscribing again with the same name, arguments and callback refreshes the same subscription rather than creating a second one. events/unsubscribe with the same identity removes it and is safe to repeat.

Each delivery is a POST of {"eventId", "name", "timestamp", "data", "cursor"} signed with Standard Webhooks HMAC using the subscription's secret (webhook-id, webhook-timestamp, webhook-signature) plus an X-MCP-Subscription-Id header. Failed deliveries are retried with backoff and keep the same eventId, so receivers can deduplicate; 410 and 413 responses are not retried. Outside ChatGPT, the same events are available as ordinary webhooks.

Full Example

Once the MCP server is configured, you can interact with email through natural language. Here is an example conversation with Claude Desktop:

# You:
Create a new inbox called "onboarding" and send a welcome email
to new-user@example.com from it.

# Claude uses create_inbox tool:
#   name: "onboarding"
#   → Created inbox: onboarding@deadsimplemail.com (inb_a1b2c3)

# Claude uses send_email tool:
#   inbox_id: "inb_a1b2c3"
#   to: "new-user@example.com"
#   subject: "Welcome aboard!"
#   body: "Hi there! Welcome to our platform. We're excited to..."
#   → Message sent: msg_x9y8z7

# Claude responds:
Done! I created the "onboarding" inbox at
onboarding@deadsimplemail.com and sent a welcome email
to new-user@example.com. The message was delivered successfully.

You can chain multiple operations naturally. Ask Claude to "check my support inbox for unread messages and reply to any that mention billing" and it will use read_messages, read_message, and reply_to_message in sequence.

Sign in to apps

Any app that offers Sign in with Dead Simple accepts an inbox as a login. Hand the agent the app's sign-in link and the sign_in_with_inbox tool completes the OpenID Connect flow with the API key the MCP server already holds: it calls POST /v1/inboxes/{inbox_id}/identity/sign-in, gets the redirect back, and follows it so the app has exchanged the code by the time the tool returns.

# You:
Sign in to https://app.example.com with your research inbox.

# Claude uses sign_in_with_inbox:
sign_in_with_inbox(
  inbox_id="6f1c2d3e-8a4b-4c5d-9e6f-0a1b2c3d4e5f",
  authorization_url="https://id.deadsimple.email/authorize?response_type=code&client_id=https%3A%2F%2Fapp.example.com&..."
)

# Result:
{ "redirect_to": "https://app.example.com/api/auth/callback/deadsimple?code=dse_idc0_...&state=xyz",
  "final_url": "https://app.example.com/dashboard", "status": 200 }

# Claude:
Signed in to app.example.com as research_9c4e1f2a@deadsimplemail.com.

Running the MCP Server Directly

You can also run the MCP server standalone for debugging or use with other MCP clients:

# Set your API key
export DSE_API_KEY="dse_your_api_key"

# Start the MCP server on stdio
python -m deadsimple.mcp

The server communicates over stdio using the MCP protocol, so it works with any client that supports the standard.

Hosted Endpoint with OAuth or Bearer Auth

There is nothing to run: the hosted server at https://api.deadsimple.email/mcp speaks Streamable HTTP and accepts two auth methods. Bearer keys work everywhere: send Authorization: Bearer dse_your_api_key with each request. OAuth 2.1 gives one-click installs in clients that support it (Claude, Cursor, Grok Bot, grok.com connectors): connect without credentials, and the client walks you through sign-in and consent on app.deadsimple.email automatically. Dynamic client registration and PKCE are supported out of the box; tokens are scoped to inbox and message operations only, with no access to billing or account administration.