SendGrid MCP Server

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 154 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 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) ✅ OpenAI Responses API / Apps SDK - via Streamable HTTP ✅ MCP Market - Hosted, one-click deploy, no install required (see 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 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:

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:

MCP Market (hosted, no install required)

MCP Market 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; 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.

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 to set your credentials and connect.

Self-hosted (Streamable HTTP)

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.

Quick start (local development)

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:

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.

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) 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 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:

Auth0

1. Sign in to your Auth0 Dashboard 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/.

export MCP_OAUTH_ISSUER="https://YOUR_TENANT.auth0.com/"

export MCP_OAUTH_AUDIENCE="https://mcp.example.com" export MCP_OAUTH_REQUIRED_SCOPES="sendgrid:read"

Okta

1. Sign in to the Okta Admin Console 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.

export MCP_OAUTH_ISSUER="https://YOUR_OKTA_DOMAIN/oauth2/YOUR_AUTH_SERVER_ID"

export MCP_OAUTH_AUDIENCE="api://sendgrid-mcp" export MCP_OAUTH_REQUIRED_SCOPES="sendgrid:read"

Microsoft Entra ID (Azure AD)

1. In the Azure Portal, go to Microsoft Entra ID → App registrations → New registration to represent this MCP server as a resource.
2. Open the new app's Expose an API page and set the Application ID URI — this becomes your audience, e.g. api:// .
3. On the same page, click Add a scope to define one, e.g. sendgrid.read.
4. Your Issuer URL is https://login.microsoftonline.com/{tenant-id}/v2.0, where {tenant-id} is the directory (tenant) ID from the app's Overview page.

export MCP_OAUTH_ISSUER="https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0"

export MCP_OAUTH_AUDIENCE="api://YOUR_CLIENT_ID" export MCP_OAUTH_REQUIRED_SCOPES="sendgrid.read"

Other providers (Google Identity Platform, Stytch, …) follow the same shape: find the OpenID Connect issuer (usually published at /.well-known/openid-configuration), define an audience/resource identifier for this server, and create a scope for it.

Whichever provider you use, also set MCP_PUBLIC_URL to the externally-reachable URL of your server (e.g. https://mcp.example.com) — clients use it during OAuth discovery.

TLS

Either terminate TLS in-process:

export TLS_KEY_FILE=/etc/ssl/private/mcp.key

export TLS_CERT_FILE=/etc/ssl/certs/mcp.crt export TLS_CA_FILE=/etc/ssl/certs/chain.pem # optional intermediates

…or terminate it at a proxy and tell the server to trust the forwarded headers