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 59 tools covering all aspects of email management and performance analysis. Then configure with your preferred MCP client (see configuration examples below). ✅ Claude Desktop - Official deskt
Add this skill
npx mdskills install deyikong/sendgrid-mcpComprehensive SendGrid MCP server with 59 tools covering email marketing, transactional emails, analytics, and contact management with excellent documentation.
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 59 tools covering all aspects of email management and performance analysis.
npm install -g sendgrid-mcp
Then configure with your preferred MCP client (see configuration examples below).
✅ Claude Desktop - Official desktop app ✅ Claude Code - Official CLI tool ✅ Cline - VS Code extension ✅ Zed Editor - Modern code editor ✅ Continue - VS Code autopilot ✅ Any MCP-compatible client
Install the SendGrid MCP server globally via npm:
npm install -g sendgrid-mcp
SG.)Add the server to your MCP client configuration (see detailed setup instructions below).
That's it! The server will run automatically when your MCP client starts.
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"
}
}
Only needed if you want to modify the server or contribute to development.
# Clone the repository
git clone https://github.com/your-username/sendgrid-mcp.git
cd sendgrid-mcp
# Install dependencies
npm install
# Build the server
npm run build
# Link for local testing
npm link
Using Local Build in MCP Clients:
{
"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"
}
}
}
}
| Variable | Required | Description | Default |
|---|---|---|---|
SENDGRID_API_KEY | ✅ | Your SendGrid API key (starts with SG.) | - |
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 | ❌ | Enable read-only mode (true/false) | true |
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 operations work normally when READ_ONLY=true:
Contact Operations:
list_contacts, get_contact, search_contacts, search_contacts_by_emailsList Operations:
list_email_lists, list_segmentsField Operations:
list_custom_fieldsSender Operations:
list_sendersCampaign & Automation Operations:
list_automations, list_single_sendsopen_automation_creator, open_automation_editoropen_single_send_creator, open_single_send_statsUtility Operations:
get_scopes, open_segment_creator, open_csv_uploaderThese 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 .env file:
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.
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 editorlist_single_sends - List all single send campaigns with metadataopen_single_send_creator - Open campaign creator in browser for visual designopen_single_send_stats - View detailed campaign performance statisticslist_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 addresseslist_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 listlist_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 cleanuplist_senders - List verified sender identitiescreate_sender - Create new sender identitydelete_sender - Delete a verified sender identityopen_csv_uploader - Open CSV upload interfacelist_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 browserTemplate Features:
send_mail - Send transactional emails (supports templates with dynamic_template_data)get_scopes - Get available API permission scopesget_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 accountsKey Metrics Tracked:
Total Tools: 59
| Category | Tools | Read-Only | Mutable | Description |
|---|---|---|---|---|
| Marketing Automations | 7 | 3 | 4 | Full automation management with CRUD operations |
| Single Send Campaigns | 3 | 3 | 0 | List campaigns, open creator, view stats |
| Contact Management | 8 | 5 | 3 | Full CRUD operations for contacts |
| Email List Management | 4 | 1 | 3 | Create, list, update, delete email lists |
| Segment Management | 4 | 2 | 2 | List, create, update, delete segments |
| Custom Fields | 4 | 1 | 3 | Manage additional contact data fields |
| Sender Identities | 3 | 1 | 2 | Manage verified sender identities |
| Contact Operations | 3 | 0 | 3 | List operations, CSV import utilities |
| Dynamic Templates | 11 | 3 | 8 | Create, manage, and version HTML email templates |
| Email Statistics | 10 | 10 | 0 | Comprehensive analytics and reporting |
| Mail Sending | 1 | 0 | 1 | Send transactional emails |
| Utilities | 1 | 1 | 0 | API scopes and permissions |
The 10 statistics tools provide comprehensive email performance analytics:
READ_ONLY=true for safetysendgrid://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 statistics📚 For extensive examples and natural language prompts, see EXAMPLE_PROMPTS.md
The following are JSON-based tool examples. For natural language examples you can use with Claude, check the comprehensive examples file.
{
"tool": "get_automation",
"arguments": {
"automation_id": "automation_id_here"
}
}
{
"tool": "update_automation_settings",
"arguments": {
"automation_id": "automation_id_here",
"title": "New Automation Name",
"status": "active"
}
}
{
"tool": "update_automation_settings",
"arguments": {
"automation_id": "automation_id_here",
"status": "paused"
}
}
{
"tool": "update_automation_step",
"arguments": {
"automation_id": "automation_id_here",
"step_id": "step_id_here",
"step_status": "active",
"wait_time": 1440
}
}
{
"tool": "delete_automation",
"arguments": {
"automation_id": "automation_id_here"
}
}
{
"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."
}
]
}
}
{
"tool": "create_contact",
"arguments": {
"contacts": [
{
"email": "newuser@example.com",
"first_name": "Jane",
"last_name": "Smith"
}
]
}
}
{
"tool": "search_contacts_by_emails",
"arguments": {
"emails": ["john@example.com", "jane@example.com"]
}
}
{
"tool": "search_contacts",
"arguments": {
"query": "email LIKE '@example.com'",
"page_size": 10
}
}
{
"tool": "update_contact",
"arguments": {
"contacts": [
{
"id": "contact_id_here",
"first_name": "John",
"last_name": "Updated"
}
]
}
}
{
"tool": "delete_contact",
"arguments": {
"contact_ids": ["contact_id_1", "contact_id_2"]
}
}
{
"tool": "remove_contact_from_lists",
"arguments": {
"list_id": "list_id_here",
"contact_ids": ["contact_id_1", "contact_id_2"]
}
}
{
"tool": "delete_sender",
"arguments": {
"sender_id": "sender_id_here"
}
}
{
"tool": "update_email_list",
"arguments": {
"list_id": "list_id_here",
"name": "Updated List Name"
}
}
{
"tool": "delete_email_list",
"arguments": {
"list_id": "list_id_here"
}
}
{
"tool": "create_custom_field",
"arguments": {
"name": "customer_tier",
"field_type": "Text"
}
}
{
"tool": "update_custom_field",
"arguments": {
"field_id": "field_id_here",
"name": "customer_level"
}
}
{
"tool": "delete_custom_field",
"arguments": {
"field_id": "field_id_here"
}
}
{
"tool": "list_email_lists",
"arguments": {
"page_size": 100
}
}
{
"tool": "update_segment",
"arguments": {
"segment_id": "segment_id_here",
"name": "Updated Segment Name"
}
}
{
"tool": "update_segment",
"arguments": {
"segment_id": "segment_id_here",
"query_dsl": "{\"and\": [{\"field\": \"email\", \"value\": \"@example.com\", \"operator\": \"like\"}]}"
}
}
{
"tool": "delete_segment",
"arguments": {
"segment_id": "segment_id_here"
}
}
{
"tool": "get_global_stats",
"arguments": {
"start_date": "2024-01-01",
"end_date": "2024-01-31",
"aggregated_by": "day"
}
}
{
"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"
}
}
{
"tool": "get_stats_by_country",
"arguments": {
"start_date": "2024-01-01",
"end_date": "2024-01-31",
"country": "US",
"aggregated_by": "week"
}
}
{
"tool": "get_stats_overview",
"arguments": {
"start_date": "2024-01-01",
"end_date": "2024-01-07",
"aggregated_by": "day",
"include_subusers": false
}
}
{
"tool": "create_html_template",
"arguments": {
"template_name": "Welcome Email",
"version_name": "Version 1.0",
"subject": "Welcome to {{companyName}}, {{firstName}}!",
"html_content": "WelcomeWelcome {{firstName}}!Thank you for joining {{companyName}}. We're excited to have you on board.
Getting Started:Complete your profileExplore our featuresContact support if neededBest regards,
The {{companyName}} Team
",
"test_data": "{\"firstName\":\"John\",\"companyName\":\"Acme Corp\"}"
}
}
{
"tool": "create_template_version",
"arguments": {
"template_id": "your_template_id",
"name": "Newsletter v1.0",
"subject": "{{month}} Newsletter - {{companyName}}",
"html_content": "{{month}} Newsletter{{#each articles}}{{title}}{{summary}}
Read More{{/each}}",
"test_data": "{\"month\":\"January\",\"companyName\":\"Acme\",\"articles\":[{\"title\":\"Article 1\",\"summary\":\"Summary here\",\"link\":\"https://example.com\"}]}"
}
}
{
"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"
}
}
The SendGrid MCP Server is distributed as an npm package for easy installation:
Package: sendgrid-mcp
Recommended - Global Installation:
npm install -g sendgrid-mcp
Alternative - Local Installation:
npm install sendgrid-mcp
npx sendgrid-mcp
To update to the latest version:
npm update -g sendgrid-mcp
This section is for developers who want to contribute to the SendGrid MCP server.
# Clone the repository
git clone https://github.com/your-username/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
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 (3 tools)
│ ├── contacts.ts # Contact tools (33 tools)
│ ├── mail.ts # Mail sending tools (2 tools)
│ ├── misc.ts # Miscellaneous tools (1 tool)
│ ├── stats.ts # Statistics tools (10 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 - Run tests (if available)# Build the project
npm run build
# Test with environment variables
SENDGRID_API_KEY="SG.your_key" READ_ONLY="true" node build/index.js
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
1. 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.
This project is licensed under the ISC License.
For issues related to:
Install via CLI
npx mdskills install deyikong/sendgrid-mcpSendGrid MCP Server is a free, open-source AI agent skill. 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 59 tools covering all aspects of email management and performance analysis. Then configure with your preferred MCP client (see configuration examples below). ✅ Claude Desktop - Official deskt
Install SendGrid MCP Server with a single command:
npx mdskills install deyikong/sendgrid-mcpThis downloads the skill files into your project and your AI agent picks them up automatically.
SendGrid MCP Server works with Claude Code, Claude Desktop, Cursor, Vscode Copilot, Windsurf, Continue Dev, Gemini Cli, Amp, Roo Code, Goose. Skills use the open SKILL.md format which is compatible with any AI coding agent that reads markdown instructions.