sendgrid-mcp
Advanced tools
Model Context Protocol (MCP) server for SendGrid API v3 - manage email marketing, automations, templates, and analytics
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.
✅ 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
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.
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 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:
https://github.com/deyikong/sendgrid-mcp), and pick a
server 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.
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.
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
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.
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.
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:
https://mcp.example.com. It doesn't need to resolve to anything; it just
needs to be unique.sendgrid:read, sendgrid:write.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"
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}.api://default) is what
you'll use for the audience — set it to something specific to this server,
e.g. api://sendgrid-mcp.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"
api://<client-id>.sendgrid.read.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
<issuer>/.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.
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:
export TRUST_PROXY=true
export MCP_PUBLIC_URL="https://mcp.example.com"
TRUST_PROXY is off by default because X-Forwarded-* headers are
client-controlled unless a proxy you control overwrites them. TLS 1.2 is the
enforced minimum in in-process mode.
OpenAI (Responses API):
{
"model": "gpt-5",
"tools": [{
"type": "mcp",
"server_label": "sendgrid",
"server_url": "https://mcp.example.com/mcp",
"authorization": "ACCESS_TOKEN"
}],
"input": "List my SendGrid automations"
}
Claude (custom connector): add https://mcp.example.com/mcp as a custom
connector. In oauth mode Claude walks the discovery flow and prompts the user
to log in; in token mode supply the bearer token directly.
The server refuses to start on misconfigurations that would quietly expose your SendGrid account, rather than coming up in a weaker mode than you intended:
TRUST_PROXYMCP_AUTH_MODE=none on anything but a loopback bindhttp:// MCP_PUBLIC_URL that is not loopbackMCP_AUTH_TOKEN, or oauth mode without an issuer
and audienceTLS_KEY_FILE and TLS_CERT_FILE set only one of the pairBeyond that:
READ_ONLY=true unless you need write and send operations. This is
the single most effective limit on blast radius — it is the difference
between a leaked token exposing analytics and one sending mail from your
domain.MCP_ALLOWED_HOSTS / MCP_ALLOWED_ORIGINS to enable DNS-rebinding
protection, which matters most for locally bound servers reachable from a
browser.SG.)Once your server is deployed (see Install the server), set your credentials and connect a client.
Set your environment variables
Open your deployed server → the Variables tab → My Credentials, and fill in:
| Variable | Required | Description |
|---|---|---|
SENDGRID_API_KEY | ✅ | Your SendGrid API key (starts with SG.) |
MCP_SERVER_NAME | ❌ | Server name for identification |
MCP_SERVER_VERSION | ❌ | Server version |
LOG_LEVEL | ❌ | Logging level (debug, info, warn, error) |
REQUEST_TIMEOUT | ❌ | API request timeout in milliseconds |
READ_ONLY | ❌ | Enable read-only mode (true/false) |
Each field saves independently — only SENDGRID_API_KEY is required.
Connect a client
Click + Connect on your server's page. MCP Market shows one-click install options for Claude Desktop, Claude Code, Codex CLI, Cursor, VS Code, Windsurf, Cline, JetBrains, Gemini CLI, Amazon Q, Goose, and Continue — pick yours and follow its prompt.
For any other client, use the Connection URL option instead, which gives
you a Streamable HTTP endpoint unique to your deployment. The examples below
use deyikong/sendgrid-mcp for illustration — yours will have your own
username and server name:
https://link.mcpmarket.com/<your-username>/<your-server-name>/mcp
Wire it up the same way as any other self-hosted endpoint, e.g.:
# Claude Code
claude mcp add --transport http sendgrid https://link.mcpmarket.com/<your-username>/<your-server-name>/mcp
# Codex CLI
codex mcp add sendgrid --url https://link.mcpmarket.com/<your-username>/<your-server-name>/mcp
MCP Market manages hosting, TLS, and availability for the deployed server; for account, billing, or deployment questions, refer to MCP Market directly rather than this repository.
The official Claude desktop application with native MCP support.
Configuration File Locations:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%/Claude/claude_desktop_config.jsonConfiguration:
{
"mcpServers": {
"sendgrid": {
"command": "sendgrid-mcp",
"env": {
"SENDGRID_API_KEY": "SG.your_api_key_here",
"READ_ONLY": "true"
}
}
}
}
Optional Configuration:
{
"mcpServers": {
"sendgrid": {
"command": "sendgrid-mcp",
"env": {
"SENDGRID_API_KEY": "SG.your_api_key_here",
"READ_ONLY": "false",
"LOG_LEVEL": "info",
"REQUEST_TIMEOUT": "30000"
}
}
}
}
After configuration:
Claude's official command-line interface with MCP support.
Installation:
npm install -g @anthropic-ai/claude-code
Configuration File Location:
~/.claude/config.jsonConfiguration:
{
"mcpServers": {
"sendgrid": {
"command": "sendgrid-mcp",
"env": {
"SENDGRID_API_KEY": "SG.your_api_key_here",
"READ_ONLY": "true"
}
}
}
}
Usage:
# Start Claude Code with SendGrid MCP
claude
# The SendGrid tools will be automatically available
# Ask Claude: "List my SendGrid automations"
Popular VS Code extension with MCP support.
Installation:
Configuration File:
Configuration:
{
"mcpServers": {
"sendgrid": {
"command": "sendgrid-mcp",
"env": {
"SENDGRID_API_KEY": "SG.your_api_key_here",
"READ_ONLY": "true"
}
}
}
}
Modern code editor with built-in AI and MCP support.
Configuration File Location:
~/.config/zed/settings.json%APPDATA%/Zed/settings.jsonConfiguration:
{
"context_servers": {
"sendgrid-mcp": {
"command": "sendgrid-mcp",
"env": {
"SENDGRID_API_KEY": "SG.your_api_key_here",
"READ_ONLY": "true"
}
}
}
}
Open-source autopilot for VS Code with MCP support.
Configuration File Location:
~/.continue/config.jsonConfiguration:
{
"experimental": {
"modelContextProtocolServers": [
{
"command": "sendgrid-mcp",
"env": {
"SENDGRID_API_KEY": "SG.your_api_key_here",
"READ_ONLY": "true"
}
}
]
}
}
For any MCP-compatible client not listed above:
Command Line:
# With environment variables
SENDGRID_API_KEY="SG.your_api_key_here" READ_ONLY="true" sendgrid-mcp
Configuration Template:
{
"command": "sendgrid-mcp",
"env": {
"SENDGRID_API_KEY": "SG.your_api_key_here",
"READ_ONLY": "true"
}
}
The server is configured entirely through environment variables. SENDGRID_API_KEY is the only required one.
| Variable | Required | Description | Default |
|---|---|---|---|
SENDGRID_API_KEY | ✅ | Your SendGrid API key (starts with SG.) | - |
READ_ONLY | ❌ | Enable read-only mode (true/false) | true |
MCP_SERVER_NAME | ❌ | Server name for identification | sendgrid-mcp |
MCP_SERVER_VERSION | ❌ | Server version | 1.0.0 |
LOG_LEVEL | ❌ | Logging level (debug, info, warn, error) | info |
REQUEST_TIMEOUT | ❌ | API request timeout in milliseconds | 30000 |
READ_ONLY defaults to true. In this mode every tool is registered and visible, but operations that create, update, delete, or send are blocked at runtime with a clear error message — only list/get/search/browser-link tools actually run. This is the safest default while you're getting set up. See Read-Only Mode for the full breakdown of what's blocked, and set READ_ONLY=false once you're ready to allow write and send operations.
These variables are set inside your MCP client's configuration (as an env block) — see Configure your MCP client. Self-hosted HTTP mode has its own set of variables (transport, auth, TLS) — see Install the server.
By default, the SendGrid MCP server runs in read-only mode (READ_ONLY=true) for safety. All tools are registered and available, but mutable operations are blocked at runtime with helpful error messages.
When READ_ONLY=true (default):
❌ Operation blocked: Server is running in READ_ONLY mode. Set READ_ONLY=false in your environment to enable write operations.
These 32 operations work normally when READ_ONLY=true:
Automations & Campaigns:
list_automations, get_automation, open_automation_creator, open_automation_editorlist_single_sends, get_single_send, open_single_send_creator, open_single_send_statsContacts, Lists & Segments:
list_contacts, get_contact, search_contacts, search_contacts_by_emailslist_email_listslist_segments, open_segment_creatorlist_custom_fieldsSenders:
list_senders, open_csv_uploaderTemplates:
list_templates, get_template, get_template_version, open_template_editorStatistics (all read-only by design):
get_global_stats, get_stats_overview, get_stats_by_browser, get_stats_by_client_type, get_stats_by_device_type, get_stats_by_mailbox_provider, get_stats_by_country, get_category_stats, get_subuser_statsUtilities:
get_scopesThese 26 operations are blocked when READ_ONLY=true:
update_automation_settings, update_automation_step, delete_automationcreate_contact, update_contact, delete_contactcreate_contact_with_lists, remove_contact_from_listscreate_email_list, update_email_list, delete_email_listcreate_custom_field, update_custom_field, delete_custom_fieldcreate_sender, delete_senderupdate_segment, delete_segmentcreate_template, update_template, delete_templatecreate_template_version, update_template_version, delete_template_versioncreate_html_templatesend_mailTo enable create, update, delete, and send operations, set READ_ONLY=false in your MCP client's env block:
{
"env": {
"SENDGRID_API_KEY": "SG.your_api_key_here",
"READ_ONLY": "false"
}
}
This will allow all mutating operations to execute normally while maintaining all read operations.
⚠️ Security Note: Only disable read-only mode if you need write access and trust the environment where the server is running.
The server exposes 154 tools grouped into 22 categories. Every tool is registered regardless of READ_ONLY mode — see Read-Only Mode for which ones are blocked by default.
📚 For natural-language prompts you can say directly to Claude, see EXAMPLE_PROMPTS.md. The examples below show the underlying JSON tool calls.
| Category | Tools | Read-Only | Mutable |
|---|---|---|---|
| Marketing Automations | 7 | 4 | 3 |
| Single Send Campaigns | 4 | 4 | 0 |
| Contact CRUD Operations | 7 | 4 | 3 |
| Email List Management | 6 | 1 | 5 |
| Segments & Custom Fields | 8 | 3 | 5 |
| Senders & Import | 4 | 2 | 2 |
| Dynamic Templates | 11 | 4 | 7 |
| Mail Sending | 1 | 0 | 1 |
| Email Statistics & Analytics | 9 | 9 | 0 |
| Utilities | 1 | 1 | 0 |
| Suppressions | 21 | 10 | 11 |
| Domain Authentication & Link Branding | 13 | 5 | 8 |
| Event & Inbound Parse Webhooks | 12 | 5 | 7 |
| Tracking Settings | 9 | 5 | 4 |
| Mail Settings | 11 | 6 | 5 |
| API Keys (read-only) | 2 | 2 | 0 |
| Alerts (read-only) | 2 | 2 | 0 |
| Teammates (read-only) | 3 | 3 | 0 |
| Dedicated IPs (read-only) | 11 | 11 | 0 |
| Design Library | 9 | 4 | 5 |
| Email Address Validation | 1 | 0 | 1 |
| Message Search | 2 | 2 | 0 |
| Total | 154 | 87 | 67 |
API Keys, Alerts, Teammates, and Dedicated IPs are deliberately read-only in this server, and SSO/certificate management isn't exposed at all — see Intentionally Unsupported Operations for why.
list_automations - List all marketing automations with metadataget_automation - Get detailed information about a specific automationupdate_automation_settings - Update automation-level settings (name, status)update_automation_step - Update individual step settings (status, wait time)delete_automation - Permanently delete an automationopen_automation_creator - Open automation creator in browseropen_automation_editor - Open specific automation editorExample — get automation details:
{
"tool": "get_automation",
"arguments": {
"automation_id": "automation_id_here"
}
}
Example — pause an entire automation:
{
"tool": "update_automation_settings",
"arguments": {
"automation_id": "automation_id_here",
"status": "paused"
}
}
Example — update a single step (status, wait time):
{
"tool": "update_automation_step",
"arguments": {
"automation_id": "automation_id_here",
"step_id": "step_id_here",
"step_status": "active",
"wait_time": 1440
}
}
Example — delete an automation:
{
"tool": "delete_automation",
"arguments": {
"automation_id": "automation_id_here"
}
}
list_single_sends - List all single send campaigns with metadataget_single_send - Retrieve detailed content and settings for a single send campaignopen_single_send_creator - Open campaign creator in browser for visual designopen_single_send_stats - View detailed campaign performance statisticsExample — get a campaign's content and settings:
{
"tool": "get_single_send",
"arguments": {
"singlesend_id": "singlesend_id_here"
}
}
list_contacts - List all contacts with pagination and filteringget_contact - Get detailed information about a specific contactcreate_contact - Create new contacts with custom fieldsupdate_contact - Update existing contact information and custom datadelete_contact - Delete contacts permanently with cleanupsearch_contacts - Search for contacts using advanced query conditionssearch_contacts_by_emails - Search for specific contacts by email addressesExample — create a new contact:
{
"tool": "create_contact",
"arguments": {
"contacts": [
{
"email": "newuser@example.com",
"first_name": "Jane",
"last_name": "Smith"
}
]
}
}
Example — search for contacts by email:
{
"tool": "search_contacts_by_emails",
"arguments": {
"emails": ["john@example.com", "jane@example.com"]
}
}
Example — search contacts with a query condition:
{
"tool": "search_contacts",
"arguments": {
"query": "email LIKE '@example.com'",
"page_size": 10
}
}
Example — update a contact:
{
"tool": "update_contact",
"arguments": {
"contacts": [
{
"id": "contact_id_here",
"first_name": "John",
"last_name": "Updated"
}
]
}
}
Example — delete contacts:
{
"tool": "delete_contact",
"arguments": {
"contact_ids": ["contact_id_1", "contact_id_2"]
}
}
list_email_lists - List all email listscreate_email_list - Create a new email listupdate_email_list - Update email list propertiesdelete_email_list - Delete an email listcreate_contact_with_lists - Create contacts and assign to listsremove_contact_from_lists - Remove contacts from a specific listExample — list email lists:
{
"tool": "list_email_lists",
"arguments": {
"page_size": 100
}
}
Example — rename an email list:
{
"tool": "update_email_list",
"arguments": {
"list_id": "list_id_here",
"name": "Updated List Name"
}
}
Example — remove contacts from a list:
{
"tool": "remove_contact_from_lists",
"arguments": {
"list_id": "list_id_here",
"contact_ids": ["contact_id_1", "contact_id_2"]
}
}
Example — delete an email list:
{
"tool": "delete_email_list",
"arguments": {
"list_id": "list_id_here"
}
}
list_segments - List dynamic segments with parent relationships and criteriaopen_segment_creator - Open segment creator in browser for visual query buildingupdate_segment - Update existing segment name or query criteria with real-time refreshdelete_segment - Delete an existing segment (contacts remain unaffected)list_custom_fields - List custom field definitions with data typescreate_custom_field - Create new custom fields (Text, Number, Date types)update_custom_field - Update existing custom field definitionsdelete_custom_field - Delete custom field definitions with data cleanupExample — rename a segment:
{
"tool": "update_segment",
"arguments": {
"segment_id": "segment_id_here",
"name": "Updated Segment Name"
}
}
Example — update a segment's query criteria:
{
"tool": "update_segment",
"arguments": {
"segment_id": "segment_id_here",
"query_dsl": "{\"and\": [{\"field\": \"email\", \"value\": \"@example.com\", \"operator\": \"like\"}]}"
}
}
Example — delete a segment:
{
"tool": "delete_segment",
"arguments": {
"segment_id": "segment_id_here"
}
}
Example — create a custom field:
{
"tool": "create_custom_field",
"arguments": {
"name": "customer_tier",
"field_type": "Text"
}
}
Example — update a custom field:
{
"tool": "update_custom_field",
"arguments": {
"field_id": "field_id_here",
"name": "customer_level"
}
}
Example — delete a custom field:
{
"tool": "delete_custom_field",
"arguments": {
"field_id": "field_id_here"
}
}
list_senders - List verified sender identitiescreate_sender - Create new sender identitydelete_sender - Delete a verified sender identityopen_csv_uploader - Open CSV upload interfaceExample — create a sender identity:
{
"tool": "create_sender",
"arguments": {
"nickname": "Marketing Team",
"from": { "email": "marketing@yourdomain.com", "name": "Your Company" },
"reply_to": { "email": "replies@yourdomain.com", "name": "Your Company" },
"address": "123 Main St",
"city": "Denver",
"state": "CO",
"zip": "80202",
"country": "United States"
}
}
Example — delete a sender identity:
{
"tool": "delete_sender",
"arguments": {
"sender_id": "sender_id_here"
}
}
list_templates - List all dynamic and legacy templatesget_template - Get details of a specific template including all versionscreate_template - Create a new dynamic templateupdate_template - Update template name and settingsdelete_template - Delete a template and all its versionscreate_template_version - Create a new version with HTML content and settingsget_template_version - Get details of a specific template versionupdate_template_version - Update version content, subject, and settingsdelete_template_version - Delete a specific template versioncreate_html_template - Create complete template with HTML content in one step (perfect for AI agents)open_template_editor - Open SendGrid's visual template editor in browserTemplates support Handlebars syntax for dynamic content ({{variable}}, {{#each}}, {{#if}}), responsive HTML with inline CSS, up to 300 versions per template, test-data previews, and automatic plain-text generation.
Example — create a complete template in one step (best for AI agents):
{
"tool": "create_html_template",
"arguments": {
"template_name": "Welcome Email",
"version_name": "Version 1.0",
"subject": "Welcome to {{companyName}}, {{firstName}}!",
"html_content": "<!DOCTYPE html><html><head><meta charset=\"utf-8\"><title>Welcome</title></head><body style=\"font-family: Arial, sans-serif; max-width: 600px; margin: 0 auto;\"><h1 style=\"color: #333;\">Welcome {{firstName}}!</h1><p>Thank you for joining {{companyName}}. We're excited to have you on board.</p></body></html>",
"test_data": "{\"firstName\":\"John\",\"companyName\":\"Acme Corp\"}"
}
}
Example — add a new version with HTML content:
{
"tool": "create_template_version",
"arguments": {
"template_id": "your_template_id",
"name": "Newsletter v1.0",
"subject": "{{month}} Newsletter - {{companyName}}",
"html_content": "<!DOCTYPE html><html><head><meta charset=\"utf-8\"></head><body><h1>{{month}} Newsletter</h1>{{#each articles}}<div><h2>{{title}}</h2><p>{{summary}}</p><a href=\"{{link}}\">Read More</a></div>{{/each}}</body></html>",
"test_data": "{\"month\":\"January\",\"companyName\":\"Acme\",\"articles\":[{\"title\":\"Article 1\",\"summary\":\"Summary here\",\"link\":\"https://example.com\"}]}"
}
}
send_mail - Send transactional emails (supports templates with dynamic template data)Example — send a simple email:
{
"tool": "send_mail",
"arguments": {
"personalizations": [
{
"to": [{"email": "recipient@example.com", "name": "John Doe"}],
"subject": "Hello from SendGrid MCP!"
}
],
"from": {"email": "sender@yourdomain.com", "name": "Your Name"},
"content": [
{
"type": "text/plain",
"value": "Hello! This email was sent via SendGrid MCP server."
}
]
}
}
Example — send using a dynamic template:
{
"tool": "send_mail",
"arguments": {
"personalizations": [
{
"to": [{"email": "user@example.com", "name": "John Doe"}],
"dynamic_template_data": {
"firstName": "John",
"companyName": "Acme Corp",
"orderNumber": "12345",
"items": [
{"name": "Product A", "price": "29.99"},
{"name": "Product B", "price": "19.99"}
]
}
}
],
"from": {"email": "noreply@yourcompany.com", "name": "Your Company"},
"template_id": "d-1234567890abcdef1234567890abcdef"
}
}
get_global_stats - Retrieve overall email performance metricsget_stats_overview - Get comprehensive statistics across multiple dimensionsget_stats_by_browser - Statistics broken down by browser type (Chrome, Firefox, Safari, etc.)get_stats_by_client_type - Statistics by email client type (desktop, mobile, webmail)get_stats_by_device_type - Statistics by device type (desktop, mobile, tablet)get_stats_by_mailbox_provider - Statistics by mailbox provider (Gmail, Outlook, Yahoo, etc.)get_stats_by_country - Statistics by country and state/provinceget_category_stats - Statistics for specific email categories (13-month history)get_subuser_stats - Statistics for specific subuser accountsTracks delivery, open, and click-through rates; bounce rates (hard/soft), spam reports, and unsubscribes; geographic performance and device preferences; email client compatibility and browser rendering; and provider-specific deliverability.
Example — global email statistics:
{
"tool": "get_global_stats",
"arguments": {
"start_date": "2024-01-01",
"end_date": "2024-01-31",
"aggregated_by": "day"
}
}
Example — statistics by mailbox provider:
{
"tool": "get_stats_by_mailbox_provider",
"arguments": {
"start_date": "2024-01-01",
"end_date": "2024-01-07",
"aggregated_by": "day",
"mailbox_providers": "gmail.com,outlook.com,yahoo.com"
}
}
Example — geographic performance statistics:
{
"tool": "get_stats_by_country",
"arguments": {
"start_date": "2024-01-01",
"end_date": "2024-01-31",
"country": "US",
"aggregated_by": "week"
}
}
Example — comprehensive statistics overview:
{
"tool": "get_stats_overview",
"arguments": {
"start_date": "2024-01-01",
"end_date": "2024-01-07",
"aggregated_by": "day",
"include_subusers": false
}
}
get_scopes - Get available API permission scopes (no arguments)list_suppression_groups - List all unsubscribe (suppression) groups on the accountcreate_suppression_group - Create a new unsubscribe (suppression) groupget_suppression_group - Get details about a specific unsubscribe (suppression) groupupdate_suppression_group - Update the name, description, or default status of an existing suppression groupdelete_suppression_group - Permanently delete an unsubscribe (suppression) group. This action cannot be undone.list_group_suppressions - List all email addresses that are unsubscribed from a specific suppression groupadd_group_suppressions - Add one or more email addresses to a specific suppression group's unsubscribe listremove_group_suppression - Remove a single email address from a specific suppression group's unsubscribe list. This only re-permits mail assigned to this group's category -- it is not a global resubscribe.list_global_suppressions - List email addresses on the account-wide global unsubscribe list, optionally filtered by a time rangeadd_global_suppression - Add recipients to the account-wide global unsubscribe list -- they will stop receiving all non-transactional mail from this accountget_global_suppression - Check whether a specific email address is on the account-wide global unsubscribe listdelete_global_suppression - Remove an email address from the account-wide global suppression list, effectively resubscribing them to non-transactional maillist_bounces - List all email addresses that have bounced, optionally filtered by a time rangeget_bounce - Get bounce event(s) recorded for a specific email addressdelete_bounce - Remove a bounce record for an email address so this address can receive mail againlist_blocks - List all email addresses currently on the blocks list, optionally filtered by a time rangedelete_block - Remove an email address from the blocks list so this address can receive mail againlist_spam_reports - List all email addresses that have reported mail as spam, optionally filtered by a time rangedelete_spam_report - Remove an email address from the spam reports list so this address can receive mail againlist_invalid_emails - List all email addresses that have been marked invalid, optionally filtered by a time rangedelete_invalid_email - Remove an email address from the invalid emails list so this address can receive mail againlist_authenticated_domains - List all authenticated (whitelabel) domains configured for sending mailget_authenticated_domain - Get detailed information about a specific authenticated domain, including its DNS recordscreate_authenticated_domain - Set up domain authentication (SPF/DKIM) for sending mail from a custom domainupdate_authenticated_domain - Update the custom SPF or default settings of an existing authenticated domaindelete_authenticated_domain - Permanently delete an authenticated domain. This action cannot be undone.validate_authenticated_domain - Check whether the domain's DNS records are correctly configured for authenticationget_default_authenticated_domain - Get the authenticated domain currently set as the default for sending maillist_branded_links - List all branded links (link whitelabels) configured for click trackingget_branded_link - Get detailed information about a specific branded link, including its DNS recordscreate_branded_link - Set up branded link tracking (click tracking through the sender's own domain instead of sendgrid.net)update_branded_link - Update the default setting of an existing branded linkdelete_branded_link - Permanently delete a branded link. This action cannot be undone.validate_branded_link - Check whether the branded link's DNS records are correctly configuredlist_event_webhooks - List all configured Event Webhook settings on the accountget_event_webhook - Get the configuration of a specific Event Webhook by IDcreate_event_webhook - Creates a new Event Webhook that POSTs email events (delivered, bounced, opened, clicked, etc.) to the given URLupdate_event_webhook - Update the configuration of an existing Event Webhookdelete_event_webhook - Permanently delete an Event Webhook configuration. This action cannot be undone.test_event_webhook - Sends a test event payload to the given webhook URL to verify it's reachable and correctly configuredlist_inbound_parse_settings - List all configured Inbound Parse webhook settings on the accountget_inbound_parse_setting - Get the Inbound Parse webhook configuration for a specific hostnamecreate_inbound_parse_setting - Configures inbound email parsing so mail sent to the given hostname is POSTed to the given URLupdate_inbound_parse_setting - Update the Inbound Parse webhook configuration for a specific hostnamedelete_inbound_parse_setting - Permanently delete an Inbound Parse webhook configuration for a hostname. This action cannot be undone.get_inbound_parse_stats - Get statistics on the number of inbound emails parsed over a given date rangeget_tracking_settings - Retrieve all tracking settings (click, open, subscription, Google Analytics) in one callget_click_tracking_settings - Retrieve the current click tracking settingupdate_click_tracking_settings - Enable or disable click tracking on links within emailsget_google_analytics_settings - Retrieve the current Google Analytics tracking settingsupdate_google_analytics_settings - Update Google Analytics tracking settings, including UTM campaign, content, medium, source, and term valuesget_open_tracking_settings - Retrieve the current open tracking settingupdate_open_tracking_settings - Enable or disable open tracking, which inserts an invisible pixel to record when an email is openedget_subscription_tracking_settings - Retrieve the current subscription tracking settingsupdate_subscription_tracking_settings - Update subscription tracking settings, including the unsubscribe link content, landing page, URL, and replacement tagget_all_mail_settings - Retrieve all mail settings (address whitelist, bounce purge, footer, forward bounce, forward spam, etc.) in one callget_address_whitelist_settings - Retrieve the current address whitelist mail setting, which controls which email addresses or domains bypass all suppression listsupdate_address_whitelist_settings - Update the address whitelist setting that controls which email addresses or domains bypass all suppression listsget_bounce_purge_settings - Retrieve the current bounce purge mail setting, which automatically purges old bounce records after a configured number of daysupdate_bounce_purge_settings - Update the bounce purge setting that automatically purges old bounce records after a configured number of daysget_footer_settings - Retrieve the current footer mail setting, which appends a footer to every outgoing emailupdate_footer_settings - Update the footer setting that appends a footer to every outgoing emailget_forward_bounce_settings - Retrieve the current forward bounce mail setting, which forwards bounce notifications to a given email addressupdate_forward_bounce_settings - Update the forward bounce setting that forwards bounce notifications to a given email addressget_forward_spam_settings - Retrieve the current forward spam mail setting, which forwards spam report notifications to a given email addressupdate_forward_spam_settings - Update the forward spam setting that forwards spam report notifications to a given email addresslist_api_keys - List all API keys on the account (names and IDs only, not the secret key values)get_api_key - Get details for a specific API key, including its scopeslist_alerts - List all usage/stats alerts configured on the accountget_alert - Get details for a specific alertlist_teammates - List all teammates (users) on the accountget_teammate - Get details for a specific teammate, including their permission scopeslist_pending_teammates - List pending teammate invitations that haven't been accepted yetlist_ip_addresses - List all IP addresses assigned to the accountget_ip_address - Get details for a specific IP address, including its warmup status and assigned subuserslist_assigned_ips - List all IP addresses that are currently assigned to a subuserlist_ip_pools - List all IP pools on the accountget_ip_pool - Get details for a specific IP pool, including the IP addresses it containsget_remaining_ips - Get the count and cost of additional dedicated IP addresses available for purchaselist_ip_warmups - List all IP addresses currently in the warmup processget_ip_warmup_status - Get the warmup status for a specific IP addresslist_allowed_ips - List IP addresses allowed to access the account via the API/UI (the access allowlist)get_allowed_ip - Get details for a specific entry in the access allowlistlist_access_activity - List recent account access attempts (successful and blocked logins/API calls)list_designs - List all custom email designs in the Design Librarycreate_design - Create a new custom email design in the Design Library from raw HTMLget_design - Get details for a specific design in the Design Libraryupdate_design - Update the content or metadata of an existing design in the Design Librarydelete_design - Permanently delete a custom design from the Design Library. This action cannot be undone.duplicate_design - Create a copy of an existing design in the Design Librarylist_prebuilt_designs - List SendGrid's built-in pre-made design templatesget_prebuilt_design - Get details for one of SendGrid's built-in pre-made designsduplicate_prebuilt_design - Create an editable copy of one of SendGrid's built-in pre-made designsvalidate_email - Check whether an email address is valid and likely to be deliverable, using SendGrid's Email Address Validation API (consumes a billed validation credit per call)search_email_activity - Search sent message activity using SendGrid's SGQL filter syntax (e.g. by recipient, status, or subject) -- useful for troubleshooting why a specific email wasn't deliveredget_message_details - Get full delivery event history and details for a single sent message by its message IDsendgrid://automations - Marketing automations datasendgrid://singlesends - Single send campaigns datasendgrid://lists - Email lists datasendgrid://contacts - Contact segments datasendgrid://suppressions - Suppression lists (bounces, spam, etc.)sendgrid://account - Account profile informationsendgrid://stats - Global email statistics and performance metrics (30-day overview)sendgrid://stats/browsers - Email statistics by browser type (7-day data)sendgrid://stats/devices - Email statistics by device type (7-day data)sendgrid://stats/geography - Email statistics by geographic location (7-day data)sendgrid://stats/providers - Email statistics by mailbox provider (7-day data)sendgrid_automation_help - Get help with marketing automationssendgrid_campaign_help - Get help with single send campaignssendgrid_contacts_help - Get help with comprehensive contact managementsendgrid_list_management_help - Get help with email list CRUD operationssendgrid_update_list_help - Get help with updating/renaming email listssendgrid_contact_crud_help - Get help with contact create/read/update/delete operationssendgrid_custom_fields_help - Get help with custom field definitions managementsendgrid_segment_management_help - Get help with managing dynamic contact segmentssendgrid_sender_management_help - Get help with sender identity managementsendgrid_templates_help - Get help with creating and managing dynamic email templatessendgrid_suppressions_help - Get help with suppression listssendgrid_settings_help - Get help with account settingssendgrid_mail_send_help - Get help with sending emailssendgrid_stats_help - Get help with analyzing email performance and statisticsThis section is for developers who want to modify the server or contribute to development.
# Clone the repository
git clone https://github.com/deyikong/sendgrid-mcp.git
cd sendgrid-mcp
# Install dependencies
npm install
# Build the project
npm run build
# Link for local development
npm link
# Test the local build
sendgrid-mcp
Using a local build in an MCP client (instead of the npm-installed binary):
{
"mcpServers": {
"sendgrid": {
"command": "node",
"args": ["/absolute/path/to/sendgrid-mcp/build/index.js"],
"env": {
"SENDGRID_API_KEY": "SG.your_api_key_here",
"READ_ONLY": "true"
}
}
}
}
src/
├── index.ts # Main entry point
├── shared/ # Shared utilities
│ ├── auth.ts # Authentication
│ ├── api.ts # SendGrid API client
│ ├── env.ts # Environment validation
│ └── types.ts # Shared types
├── tools/ # Tool definitions
│ ├── automations.ts # Automation tools (7 tools)
│ ├── campaigns.ts # Campaign tools (4 tools)
│ ├── contacts.ts # Contact, list, segment & sender tools (25 tools)
│ ├── mail.ts # Mail sending tools (1 tool)
│ ├── misc.ts # Miscellaneous tools (1 tool)
│ ├── stats.ts # Statistics tools (9 tools)
│ └── templates.ts # Template tools (11 tools)
├── resources/ # Resource definitions
│ └── sendgrid.ts # MCP resources
└── prompts/ # Prompt definitions
└── help.ts # Help prompts
src/tools/src/tools/index.tsnpm run build to compilenpm run build - Compile TypeScript to JavaScriptnpm start - Run the compiled servernpm test - Build and run the test suite# Build the project
npm run build
# Test with environment variables
SENDGRID_API_KEY="SG.your_key" READ_ONLY="true" node build/index.js
For manually verifying a real client can connect over each HTTP auth mode (token, none, TLS, OAuth) rather than just the automated suite, see TESTING.md.
For maintainers only:
Update version in package.json:
npm version patch # or minor, major
Push changes and tags:
git push && git push --tags
Create GitHub release - this triggers automatic npm publishing via GitHub Actions
sendgrid-mcp on npm — update with npm update -g sendgrid-mcp1. Server Not Found / Command Not Found
Error: sendgrid-mcp: command not found
Solution:
npm install -g sendgrid-mcpnpm config get prefixnpm uninstall -g sendgrid-mcp && npm install -g sendgrid-mcp2. Invalid API Key
Error: SENDGRID_API_KEY must start with 'SG.'
Solution:
SG.3. Permission Errors
Error: 403 Forbidden
Solution:
4. Read-Only Mode Blocking Operations
❌ Operation blocked: Server is running in READ_ONLY mode
Solution:
READ_ONLY: "false" in your MCP client configuration{
"env": {
"SENDGRID_API_KEY": "SG.your_key",
"READ_ONLY": "false"
}
}
5. MCP Client Not Detecting Server
Solution:
6. Connection Timeout
Error: Request timeout
Solution:
{
"env": {
"REQUEST_TIMEOUT": "60000"
}
}
Enable detailed logging by setting the LOG_LEVEL:
{
"env": {
"SENDGRID_API_KEY": "SG.your_key",
"LOG_LEVEL": "debug"
}
}
This will provide detailed information about API requests and responses.
Found a vulnerability? Please report it privately rather than opening a public issue — see SECURITY.md.
A handful of SendGrid API capabilities are deliberately left out of this server, on top of whatever READ_ONLY mode blocks at runtime. These aren't gaps to be filled later — they're excluded because letting an LLM call them autonomously carries account-wide blast radius that a READ_ONLY toggle alone doesn't mitigate (an operator running with READ_ONLY=false for legitimate marketing-automation writes shouldn't also be one prompt-injected tool call away from losing account access or api budget):
list_api_keys/get_api_key are exposed. Minting or deleting API keys is a classic prompt-injection target: a malicious webpage or email an agent processes could try to trick it into creating a new key and exfiltrating it.list_teammates/get_teammate/list_pending_teammates are exposed. Adding, removing, or re-permissioning teammates is account access control with the same injection risk as API keys.If you need any of these for a specific automation, use the SendGrid dashboard or API directly rather than requesting this server add them — that's a deliberate design boundary, not an oversight.
This project is licensed under the ISC License.
For issues related to:
I work at SendGrid and maintain this project. Feedback, bug reports, and feature requests are always welcome — please open an issue or start a discussion on the repository.
FAQs
Model Context Protocol (MCP) server for SendGrid API v3 - manage email marketing, automations, templates, and analytics
The npm package sendgrid-mcp receives a total of 191 weekly downloads. As such, sendgrid-mcp popularity was classified as not popular.
We found that sendgrid-mcp demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Research
/Security News
A malicious Firefox extension fetches its payload after installation to evade detection, steal Google session cookies, and automate account takeover.
Research
/Security News
The compromise affects MemTensor's MemOS, an open source memory framework for large language models (LLMs) and AI agents. Both npm package @memtensor/memos-cloud-openclaw-plugin and the PyPI package MemoryOS are compromised. They drop cross-platform Go binaries that exfiltrate developer secrets.
Security News
Lovable’s OJ rewrites Vite’s dev server in Rust, reducing memory use and preview times as AI lowers the cost of open source reimplementation.