Groundmail MCP

• Hosted: https://mcp.groundmail.dev/mcp (Streamable HTTP). OAuth sign-in, or Authorization: Bearer gm_….
• Local: npx -y groundmail-mcp (stdio) or npx -y groundmail-mcp --http (http://127.0.0.1:3000/mcp), with GROUNDMAIL_API_KEY=gm_…. Optional GROUNDMAIL_API_URL.

Always use the full hosted URL including /mcp. For API rules (sandbox, idempotency, error codes) also load the groundmail skill.

Install

Claude Code

claude mcp add --transport http groundmail https://mcp.groundmail.dev/mcp

Then /mcp → groundmail → Authenticate, and sign in to Groundmail in the browser. Headless or CI:

claude mcp add --transport http groundmail https://mcp.groundmail.dev/mcp \
  --header "Authorization: Bearer $GROUNDMAIL_API_KEY"
# or local stdio
claude mcp add groundmail --env GROUNDMAIL_API_KEY=gm_your_key_here -- npx -y groundmail-mcp

Claude (claude.ai / Desktop)

Settings → Connectors → Add custom connector → URL https://mcp.groundmail.dev/mcp → Connect → sign in to Groundmail.

ChatGPT

Developer mode (Settings → Apps & Connectors → Advanced) → Create connector → URL https://mcp.groundmail.dev/mcp, authentication OAuth → sign in to Groundmail.

Cursor

.cursor/mcp.json or ~/.cursor/mcp.json, hosted with an API key:

{
  "mcpServers": {
    "groundmail": {
      "url": "https://mcp.groundmail.dev/mcp",
      "headers": { "Authorization": "Bearer gm_your_key_here" }
    }
  }
}

Or local stdio:

{
  "mcpServers": {
    "groundmail": {
      "command": "npx",
      "args": ["-y", "groundmail-mcp"],
      "env": { "GROUNDMAIL_API_KEY": "gm_your_key_here" }
    }
  }
}

Restart Cursor after editing. The dashboard Install in Cursor button writes this with the key filled in. Keep config files with keys out of git.

Tools

Full list with one line per tool: https://docs.groundmail.dev/ai/mcp

Rules for agents

1. First send: from noreply@mail.groundmail.dev, to the user's Groundmail account email. Other recipients are refused until a domain is verified and the user has set up billing in the dashboard.
2. Confirm with the user before send_email to anyone but them, create_domain, delete_webhook, resend_webhook_delivery, remove_suppression or remove_category_opt_out.
3. Failed tool calls return the API message, code: … with the HTTP status, and a how to fix link to https://docs.groundmail.dev/errors#<code>. Follow it instead of retrying blindly.
4. send_email does not take an idempotency key. For app code that retries, use the SDK or HTTP with Idempotency-Key.
5. Never ask for or accept payment card numbers, passwords, government ID numbers, health information or other sensitive personal data in chat; the user enters billing and account details only in the Groundmail dashboard.

MCP vs SDK

Never put the API key in client-side code, even when using MCP during development.