Groundmail MCP server

Expose Groundmail to Cursor, Claude Code, or any MCP client with a curated tool surface.

Package: groundmail-mcp on npm
Version: 0.4.0

Docs index for agents: llms.txt · Agent Skills · Agent skill notes

Transports

Local HTTP listens on http://127.0.0.1:3000/mcp by default (--host / --port override). GET /health is unauthenticated (local and hosted).

Hosted OAuth (recommended)

Remote MCP clients (Cursor, Claude Code) can connect without pasting an API key:

1. Add the hosted URL only — https://mcp.groundmail.dev/mcp (no headers block).
2. The client discovers OAuth via WWW-Authenticate + /.well-known/oauth-protected-resource.
3. Sign in on app.groundmail.dev, approve access, and the client receives tokens.

Authorization server metadata: https://app.groundmail.dev/.well-known/oauth-authorization-server

Bearer gm_… still works for scripts, CI, and advanced setups.

Install in Cursor (stdio)

1. Create an API key in the dashboard (or use Get started → Copy setup prompt / Install in Cursor).
2. Add to .cursor/mcp.json (or global ~/.cursor/mcp.json):

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

3. Restart Cursor. The tools appear in Agent chat.

Optional: set GROUNDMAIL_API_URL when pointing at a local app (http://localhost:3003/api).

The dashboard Install in Cursor button generates a deeplink with your key pre-filled.

Cursor (HTTP)

Terminal:

npx -y groundmail-mcp --http --port 3000

.cursor/mcp.json (URL + Bearer; exact shape depends on Cursor version):

{
  "mcpServers": {
    "groundmail": {
      "url": "http://127.0.0.1:3000/mcp",
      "headers": {
        "Authorization": "Bearer gm_your_key_here"
      }
    }
  }
}

Replit (hosted remote)

One-click install of the hosted server (OAuth — no API key in the link):

App-side sends in a Replit project still use Secrets + code — see Replit builder guide.

Cursor (hosted remote)

OAuth (recommended): no local process, no API key in config.

{
  "mcpServers": {
    "groundmail": {
      "url": "https://mcp.groundmail.dev/mcp"
    }
  }
}

Cursor runs the browser OAuth flow on first connect.

Bearer (advanced): dashboard Copy hosted MCP JSON pre-fills your key.

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

Health check: GET https://mcp.groundmail.dev/health

Claude Code

# stdio
claude mcp add --transport stdio groundmail -- npx -y groundmail-mcp

# HTTP (local — start --http server first)
claude mcp add --transport http groundmail http://127.0.0.1:3000/mcp

# HTTP (hosted)
claude mcp add --transport http groundmail https://mcp.groundmail.dev/mcp

Export GROUNDMAIL_API_KEY=gm_… for stdio. For HTTP (local or hosted), configure Bearer headers in the client.

Tools

All tools call the groundmail SDK (no duplicate HTTP).

send_email

Inputs: from, to, subject, optional html / text / reply_to.

Sandbox: if from is noreply@mail.groundmail.dev, recipients must match the account email.

send_test_webhook_event

Inputs:

• event (required) — e.g. email.bounced, email.delivered
• optional email_id (msg_…)
• optional deliver (default true) — enqueue to subscribed webhooks

Install

npx -y groundmail-mcp
npx -y groundmail-mcp --http --port 3000
# or
npm install -g groundmail-mcp

For agents without MCP, use the dashboard Copy setup prompt flow, Agent Skills, or agent-skill.md with llms.txt.

The package is also listed on Smithery for agent discovery.