sendgrid-mcp

# SendGrid MCP Server

A Model Context Protocol (MCP) server that provides comprehensive access to SendGrid's API v3 for email marketing, transactional email operations, dynamic template management, and detailed analytics. Features 58 tools covering all aspects of email management and performance analysis.

*Built and maintained by a SendGrid engineer, as an independent project — not an official SendGrid product.*

> See [RELEASES.md](./RELEASES.md) for what's changed in the latest release.

## Features

- **Marketing Automations**: Create and manage email automation workflows
- **Single Send Campaigns**: Manage one-time email campaigns with detailed performance tracking
- **Contact Management**: Complete CRUD operations for contacts with advanced search and bulk operations
- **Email Statistics & Analytics**: Multi-dimensional performance analysis across browsers, devices, geography, and email providers with 13-month historical data
- **Dynamic Segment Management**: Create, update, and delete contact segments with complex filtering criteria that automatically refresh
- **Dynamic Template Management**: Create, manage, and version HTML email templates with Handlebars support for personalization
- **Custom Fields Management**: Define and manage additional contact data fields for enhanced targeting
- **Mail Sending**: Send transactional emails via SendGrid with full personalization support
- **Sender Identity Management**: Manage verified sender identities with authentication tracking
- **Suppression Lists**: Manage bounces, spam reports, and unsubscribes for deliverability optimization
- **Account Settings**: Access account details and configuration management
- **Browser Integration**: Quick links to SendGrid web interface for visual operations
- **Read-Only Safety Mode**: Secure operation mode prevents accidental data modification while maintaining full analytics access

## Supported MCP Clients

✅ **Claude Desktop** - Official desktop app
✅ **Claude Code** - Official CLI tool
✅ **Claude custom connectors** - via Streamable HTTP (see [Install the server](#1-install-the-server))
✅ **OpenAI Responses API / Apps SDK** - via Streamable HTTP
✅ **MCP Market** - Hosted, one-click deploy, no install required (see [Install the server](#1-install-the-server))
✅ **Cline** - VS Code extension
✅ **Zed Editor** - Modern code editor
✅ **Continue** - VS Code autopilot
✅ **Codex CLI** - via Streamable HTTP
✅ **Any MCP-compatible client**

## Getting Started

Follow these steps in order — by the end you'll have the server installed (or deployed), your SendGrid API key set, and your MCP client connected.

This is the actual request path, whichever client you end up using — some
launch the server locally over stdio, others reach it over the network via
Streamable HTTP (MCP Market, self-hosted), which adds a choice of client
auth on top:

```
                                ┌──────────┐
                                │  Client  │
                                └────┬─────┘
              ┌──────────────────────┴───────────────────┐
              │                                          │
           stdio (local subprocess)        HTTP (network)
              │               auth: none | token | oauth │
              │                                          │
              └──────────────────────┬───────────────────┘
                                     ▼
                           ┌────────────────────┐
                           │     MCP Server     │
                           │    (this repo)     │
                           └─────────┬──────────┘
                                     │  SENDGRID_API_KEY
                                     │  (always required, any transport)
                                     ▼
                           ┌────────────────────┐
                           │    SendGrid API    │
                           └────────────────────┘
```

`SENDGRID_API_KEY` is required no matter which path you take. `READ_ONLY=true`
(the default) is a further gate *inside* the MCP Server box — it blocks
create/update/delete/send tools once a request is already in, regardless of
which branch it arrived on. See [Environment Variables](#environment-variables)
for the full list of what you can configure.

### 1. Install the server

Install it **locally** if your client launches it itself, or go **remote** if it connects over the network instead.

**Local (stdio)** — for Claude Desktop, Claude Code, Cline, Zed, Continue, or any client that runs the server as a subprocess:

```bash
npm install -g sendgrid-mcp
```

This installs the `sendgrid-mcp` command globally, which your MCP client will launch as a subprocess. Requires Node.js 20+.

**Remote (HTTP)** — nothing to install locally; pick one:

<details>
<summary>MCP Market (hosted, no install required)</summary>

[MCP Market](https://app.mcpmarket.com/deyikong/mcp/sendgrid) deploys and hosts this server for you — nothing to install locally and no environment variables to manage on your machine. You still need a [SendGrid API key](#2-get-your-sendgrid-api-key); you'll enter it into MCP Market instead of your own shell/config.

From MCP Market's **MCP Servers** page, deploy a custom MCP from either source:

- **GitHub** — select the GitHub source, choose Public or Private repo, paste
  the repo URL (`https://github.com/deyikong/sendgrid-mcp`), and pick a
  server name.
- **npm** — select the npm source, enter the package name (`sendgrid-mcp`),
  and pick a server name.

![Deploying from a GitHub repo](docs/images/mcp-market/github-install.png)
![Deploying from an npm package](docs/images/mcp-market/npm-install.png)

Either way, MCP Market builds and runs it for you; it shows up under
**MCP Servers** with a `Running` status once ready. Continue to
[Configure your MCP client](#3-configure-your-mcp-client) to set your
credentials and connect.

---

</details>

<details>
<summary>Self-hosted (Streamable HTTP)</summary>

Run the server yourself and expose it over Streamable HTTP instead of letting
a client launch it locally — for Claude custom connectors, OpenAI's Responses
API `mcp` tool / Apps SDK, or any other remote client.

The MCP endpoint is `POST /mcp`; `GET /health` returns a status document for
load balancers. Requests are handled **statelessly** (no session id required),
which is what hosted clients expect.

`none`/`token`/`oauth` below are not alternate ways to *connect* — they're
three different locks on the one new door (HTTP), as shown in the
[request-flow diagram above](#getting-started).

#### Quick start (local development)

```bash
export SENDGRID_API_KEY="SG.your_api_key_here"
export MCP_TRANSPORT=http
export MCP_AUTH_MODE=token
export MCP_AUTH_TOKEN="$(openssl rand -hex 32)"

sendgrid-mcp
```

#### Authentication

Set `MCP_AUTH_MODE` to one of:

| Mode | Use for | Requires |
|------|---------|----------|
| `oauth` | Production / remote clients | `MCP_OAUTH_ISSUER`, `MCP_OAUTH_AUDIENCE` |
| `token` | Local dev, simple self-hosting | `MCP_AUTH_TOKEN` (16+ chars) |
| `none` | Loopback development only | — refuses to start on a public bind |

**OAuth mode** makes this server an OAuth 2.1 **resource server**. It does not
issue or store credentials — it verifies access tokens minted by your existing
identity provider (Auth0, Okta, Entra ID, Google, Stytch, …) against that
provider's published JWKS.

```bash
export MCP_AUTH_MODE=oauth
export MCP_OAUTH_ISSUER="https://your-tenant.auth0.com"
export MCP_OAUTH_AUDIENCE="https://mcp.example.com"
export MCP_OAUTH_REQUIRED_SCOPES="sendgrid:read"
export MCP_PUBLIC_URL="https://mcp.example.com"
```

`SENDGRID_API_KEY` (see the [diagram in Getting Started](#getting-started))
is still required alongside these — OAuth only controls who can reach the server, not what the server
uses to talk to SendGrid.

The server publishes [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728)
Protected Resource Metadata at `/.well-known/oauth-protected-resource`, so
clients discover your authorization server automatically: an unauthenticated
request gets a `401` whose `WWW-Authenticate` header points at that document,
the client reads it, sends the user to your IdP to log in, and retries with the
resulting token.

Tokens are rejected (`401`) if expired, wrongly signed, or issued for a
different issuer or audience; a valid token missing a required scope gets `403`.

#### Setting up your identity provider

Whichever provider you use, you're configuring the same three things: an
**issuer URL**, an **audience** (a stable identifier for this API resource),
and a **scope** clients will request. A few concrete walkthroughs:

<details>
<summary>Auth0</summary>

1. Sign in to your [Auth0 Dashboard](https://manage.auth0.com/) and go to
   **Applications → APIs → Create API**.
2. Set an **Identifier** — this is your audience, e.g.
   `https://mcp.example.com`. It doesn't need to resolve to anything; it just
   needs to be unique.
3. Under the API's **Permissions** tab, add the scopes your server should
   require, e.g. `sendgrid:read`, `sendgrid:write`.
4. Your **Issuer URL** is your tenant domain, shown on the API's *Settings*
   tab: `https://YOUR_TENANT.auth0.com/`.

```bash
export MCP_OAUTH_ISSUER="https://YOUR_TENANT.auth0.com/"
export MCP_OAUTH_AUDIENCE="https://mcp.example.com"
export MCP_OAUTH_REQUIRED_SCOPES="sendgrid:read"
```

</details>

<details>
<summary>Okta</summary>

1. Sign in to the [Okta Admin Console](https://login.okta.com/) and go to
   **Security → API → Authorization Servers**.
2. Use the `default` authorization server, or create a new one. Its
   **Issuer URI**, shown at the top of the server's settings page, looks like
   `https://{yourOktaDomain}/oauth2/{authServerId}`.
3. On the same page, the **Audience** field (default `api://default`) is what
   you'll use for the audience — set it to something specific to this server,
   e.g. `api://sendgrid-mcp`.
4. Open the **Scopes** tab and add a scope, e.g. `sendgrid:read`.