groundmail-mcp 0.5.12 → 0.5.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +91 -40
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -1,27 +1,77 @@
1
- # groundmail-mcp
1
+ <p align="center">
2
+ <a href="https://groundmail.dev">
3
+ <picture>
4
+ <source media="(prefers-color-scheme: dark)" srcset="https://app.groundmail.dev/images/github/readme-logo-dark.png">
5
+ <img alt="Groundmail" src="https://app.groundmail.dev/images/github/readme-logo-light.png" height="44">
6
+ </picture>
7
+ </a>
8
+ </p>
9
+
10
+ <h1 align="center">Groundmail MCP server</h1>
11
+
12
+ <p align="center">
13
+ Send transactional email and manage domains, templates, webhooks and suppressions<br>
14
+ from Claude, Claude Code, ChatGPT, Cursor and any other MCP client.
15
+ </p>
16
+
17
+ <p align="center">
18
+ <a href="https://www.npmjs.com/package/groundmail-mcp"><img alt="npm" src="https://img.shields.io/npm/v/groundmail-mcp?color=a3461f&label=npm"></a>
19
+ <a href="https://registry.modelcontextprotocol.io"><img alt="MCP registry" src="https://img.shields.io/badge/MCP%20registry-io.github.Groundmail%2Fgroundmail-241c15"></a>
20
+ <a href="./LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-b48f62"></a>
21
+ </p>
22
+
23
+ <p align="center">
24
+ <a href="https://docs.groundmail.dev/ai/mcp">Docs</a> ·
25
+ <a href="https://app.groundmail.dev/signup">Get a free account</a> ·
26
+ <a href="https://groundmail.dev">groundmail.dev</a>
27
+ </p>
2
28
 
3
- MCP server for [Groundmail](https://groundmail.dev): send email and manage domains, webhooks, suppressions and templates from Claude, Claude Code, ChatGPT, Cursor and other MCP clients.
29
+ ---
30
+
31
+ ## Quick start
32
+
33
+ The fastest way is the hosted server. Add the URL, sign in through your browser, and you're done. No API key to copy.
34
+
35
+ ```
36
+ https://mcp.groundmail.dev/mcp
37
+ ```
38
+
39
+ | Client | How to connect |
40
+ |--------|----------------|
41
+ | **Claude Code** | `claude mcp add --transport http groundmail https://mcp.groundmail.dev/mcp`, then run `/mcp`, pick groundmail and choose Authenticate |
42
+ | **Cursor** | Add `{ "mcpServers": { "groundmail": { "url": "https://mcp.groundmail.dev/mcp" } } }` to `.cursor/mcp.json`; Cursor shows "Needs login" |
43
+ | **Claude.ai** | Settings → Connectors → Add custom connector → paste the URL |
44
+ | **ChatGPT** | Settings → Apps & Connectors → Create (developer mode) → paste the URL, authentication OAuth |
45
+
46
+ When you connect, you choose the access: **Full**, **Send only** or **Read only**. Revoke it any time in Groundmail under Settings → CLIs & agents.
4
47
 
5
- **Install:** `npx -y groundmail-mcp` · **Docs:** https://docs.groundmail.dev/ai/mcp
48
+ ## What you can ask for
49
+
50
+ > "Send a password reset email to ada@example.com from noreply@mail.acme.com."
51
+ >
52
+ > "Did my last 10 emails get delivered? Show any bounces."
53
+ >
54
+ > "Add mail.acme.com as a sending domain and apply the DNS records on Cloudflare."
55
+ >
56
+ > "How is my deliverability over the last 7 days?"
57
+
58
+ Tools cover emails (send, schedule, cancel, look up), domains (add, apply DNS, verify), templates, webhooks, suppressions and deliverability. Each tool carries read-only and destructive annotations and an output schema. Full list: [docs.groundmail.dev/ai/mcp](https://docs.groundmail.dev/ai/mcp).
6
59
 
7
60
  ## Transports
8
61
 
9
62
  | Mode | Command / URL | Auth |
10
63
  |------|---------------|------|
11
- | **stdio** (default) | `npx -y groundmail-mcp` | `GROUNDMAIL_API_KEY=gm_…` |
12
- | **HTTP** (local) | `npx -y groundmail-mcp --http --port 3000` | `Authorization: Bearer gm_…` on each request |
13
- | **HTTP** (hosted) | `https://mcp.groundmail.dev/mcp` | **OAuth** (recommended) or `Authorization: Bearer gm_…` |
64
+ | **HTTP (hosted)** | `https://mcp.groundmail.dev/mcp` | **OAuth** (recommended) or `Authorization: Bearer gm_…` |
65
+ | **stdio** | `npx -y groundmail-mcp` | `GROUNDMAIL_API_KEY=gm_…` |
66
+ | **HTTP (local)** | `npx -y groundmail-mcp --http --port 3000` | `Authorization: Bearer gm_…` on each request |
14
67
 
15
- Optional: `GROUNDMAIL_API_URL` (e.g. `http://localhost:3003/api` for local API).
68
+ Optional: `GROUNDMAIL_API_URL` (for example `http://localhost:3003/api` against a local API).
16
69
 
17
- Local HTTP endpoint: `http://127.0.0.1:3000/mcp` · health: `GET /health`
70
+ Local HTTP endpoint: `http://127.0.0.1:3000/mcp` · health: `GET /health`
18
71
  Hosted health: `GET https://mcp.groundmail.dev/health`
19
72
 
20
- Hosted OAuth: add only `"url": "https://mcp.groundmail.dev/mcp"` — the client runs the browser consent flow. Bearer `gm_…` still works for advanced setups.
21
-
22
- ---
23
-
24
- ## Cursor (stdio)
73
+ <details>
74
+ <summary><strong>Cursor with an API key (stdio)</strong></summary>
25
75
 
26
76
  `.cursor/mcp.json`:
27
77
 
@@ -39,7 +89,10 @@ Hosted OAuth: add only `"url": "https://mcp.groundmail.dev/mcp"` — the client
39
89
  }
40
90
  ```
41
91
 
42
- ### Cursor (local HTTP)
92
+ </details>
93
+
94
+ <details>
95
+ <summary><strong>Cursor with an API key (local or hosted HTTP)</strong></summary>
43
96
 
44
97
  ```bash
45
98
  npx -y groundmail-mcp --http --port 3000
@@ -58,29 +111,14 @@ npx -y groundmail-mcp --http --port 3000
58
111
  }
59
112
  ```
60
113
 
61
- ### Cursor (hosted)
114
+ For the hosted server with a key instead of OAuth, use `"url": "https://mcp.groundmail.dev/mcp"` with the same header.
62
115
 
63
- ```json
64
- {
65
- "mcpServers": {
66
- "groundmail": {
67
- "url": "https://mcp.groundmail.dev/mcp",
68
- "headers": {
69
- "Authorization": "Bearer gm_your_key_here"
70
- }
71
- }
72
- }
73
- }
74
- ```
116
+ </details>
75
117
 
76
- ---
77
-
78
- ## Claude Code
118
+ <details>
119
+ <summary><strong>Claude Code with an API key</strong></summary>
79
120
 
80
121
  ```bash
81
- # Hosted, OAuth: then run /mcp, pick groundmail, Authenticate
82
- claude mcp add --transport http groundmail https://mcp.groundmail.dev/mcp
83
-
84
122
  # Hosted, API key
85
123
  claude mcp add --transport http groundmail https://mcp.groundmail.dev/mcp \
86
124
  --header "Authorization: Bearer $GROUNDMAIL_API_KEY"
@@ -89,16 +127,29 @@ claude mcp add --transport http groundmail https://mcp.groundmail.dev/mcp \
89
127
  claude mcp add groundmail --env GROUNDMAIL_API_KEY=gm_your_key_here -- npx -y groundmail-mcp
90
128
  ```
91
129
 
92
- ## Claude and ChatGPT
130
+ </details>
93
131
 
94
- Add a custom connector with the URL `https://mcp.groundmail.dev/mcp` and sign in to Groundmail when prompted (ChatGPT needs developer mode). Step-by-step: https://docs.groundmail.dev/ai/mcp
132
+ Want your coding agent to know Groundmail too? Install the [agent skills](https://github.com/Groundmail/groundmail-skills): `npx skills add Groundmail/groundmail-skills -y`.
95
133
 
96
- ---
134
+ ## Why Groundmail
97
135
 
98
- ## Tools
136
+ - **Our own mail servers and IP space.** Your password resets and receipts don't share a pool with bulk marketing senders.
137
+ - **Transactional email only.** No newsletters or cold outreach on the platform, which keeps the sending reputation clean.
138
+ - **Start free.** 3,000 emails a month on the Free plan; Pro is 50,000 emails for $20/month. Dedicated IPs on Scale.
139
+ - **Built for code and for agents.** REST API, SMTP, SDKs for Node, Python, Go, PHP and Ruby, a CLI, and an MCP server for Claude, ChatGPT and Cursor.
99
140
 
100
- See https://docs.groundmail.dev/ai/mcp — emails, domains, webhooks, suppressions, templates, deliverability, webhook test.
141
+ ## All Groundmail libraries
101
142
 
102
- ## License
143
+ | Use | Package |
144
+ |-----|---------|
145
+ | Node.js / TypeScript | [`groundmail`](https://www.npmjs.com/package/groundmail) on npm |
146
+ | Python, Go, Ruby | [Groundmail/groundmail-sdks](https://github.com/Groundmail/groundmail-sdks) |
147
+ | PHP | [Groundmail/groundmail-php](https://github.com/Groundmail/groundmail-php) |
148
+ | Laravel | [Groundmail/groundmail-laravel](https://github.com/Groundmail/groundmail-laravel) |
149
+ | Symfony Mailer | [Groundmail/groundmail-symfony-mailer](https://github.com/Groundmail/groundmail-symfony-mailer) |
150
+ | Nodemailer | [Groundmail/groundmail-nodemailer](https://github.com/Groundmail/groundmail-nodemailer) |
151
+ | CLI | [`groundmail-cli`](https://www.npmjs.com/package/groundmail-cli) on npm |
152
+ | MCP server (Claude, ChatGPT, Cursor) | [Groundmail/groundmail-mcp](https://github.com/Groundmail/groundmail-mcp) |
153
+ | Agent skills and Claude Code plugin | [Groundmail/groundmail-skills](https://github.com/Groundmail/groundmail-skills) |
103
154
 
104
- MIT
155
+ [Website](https://groundmail.dev) · [Docs](https://docs.groundmail.dev) · [Pricing](https://groundmail.dev/pricing) · [Sign up free](https://app.groundmail.dev/signup)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "groundmail-mcp",
3
- "version": "0.5.12",
3
+ "version": "0.5.14",
4
4
  "mcpName": "io.github.Groundmail/groundmail",
5
5
  "description": "Groundmail MCP server: send transactional email, manage domains, templates, webhooks and suppressions from Claude, Cursor, ChatGPT and other MCP clients",
6
6
  "license": "MIT",
@@ -41,7 +41,7 @@
41
41
  },
42
42
  "dependencies": {
43
43
  "@modelcontextprotocol/sdk": "^1.30.0",
44
- "groundmail": "0.14.4"
44
+ "groundmail": "0.14.5"
45
45
  },
46
46
  "devDependencies": {
47
47
  "tsup": "^8.5.0",