Overview

This project implements an MCP (Model Context Protocol) server that connects AI assistants and tools to SendGrid for transactional email, template management, and basic analytics. The server exposes a small set of MCP-compatible HTTP endpoints so a language model or assistant can request actions such as rendering a template, sending an email, listing templates, and fetching email statistics — all without embedding SendGrid API keys directly in the assistant.

Using an MCP server helps teams centralize email operations, control templates, and collect usage metrics while letting assistants perform email tasks programmatically. It is particularly useful in workflows where an AI agent needs to trigger emails (welcome flows, notifications, support followups) or where developers want to audit and limit what the assistant can send.

Features

Send transactional emails using SendGrid templates and dynamic data
List and inspect SendGrid templates and versions
Render templates with dynamic substitution data (preview API)
Fetch basic email statistics and analytics (deliveries, open/click rates)
MCP-compatible endpoints and a simple JSON manifest for assistant integration
Configurable via environment variables and runnable as a Docker container

Installation / Configuration

Prerequisites:

Node.js 16+ (or a compatible runtime)
A SendGrid API key with Mail Send and Template Read permissions

Clone and install:

git clone https://github.com/recepyavuz0/sendgrid-mcp-server.git
cd sendgrid-mcp-server
npm install

Environment variables (example .env):

PORT=3000
SENDGRID_API_KEY=SG.xxxxxxxx_your_sendgrid_api_key
[email protected]
ALLOWLISTED_DOMAINS=example.com,example.org

Start the server:

npm run start
# or for development
npm run dev

Docker:

# Build
docker build -t sendgrid-mcp-server .

# Run
docker run -e SENDGRID_API_KEY=SG.xxx -e [email protected] -p 3000:3000 sendgrid-mcp-server

Available Tools / Resources

Typical HTTP endpoints exposed by the MCP server (adjust based on the server’s implementation):

Endpoint	Method	Description
/mcp/templates	GET	List templates and versions
/mcp/templates/:id	GET	Get template details (including versions)
/mcp/templates/:id/render	POST	Render a template with dynamic data (preview)
/mcp/send	POST	Send an email using template_id or raw content
/mcp/stats	GET	Fetch aggregated email statistics (by date range)
/health	GET	Basic health check

Example MCP tool manifest snippet (JSON) to register with an assistant:

{
  "schema_version": "v0",
  "name_for_model": "sendgrid_mcp",
  "description_for_model": "Send transactional emails, manage templates, and fetch email analytics via SendGrid.",
  "api": {
    "type": "mcp",
    "url": "https://your-server.example.com/mcp"
  }
}

Example send payload (POST /mcp/send):

{
  "to": "[email protected]",
  "from": "[email protected]",
  "template_id": "d-1234567890abcdef",
  "dynamic_template_data": {
    "firstName": "Alex",
    "resetLink": "https://example.com/reset?token=abc"
  },
  "subject": "Reset your password"
}

Use Cases

Automated onboarding emails from an assistant
- Trigger: a user signs up via a chat flow.
- Assistant action: call POST /mcp/send with the onboarding template_id and dynamic data (name, activation link).
- Result: user receives a templated, personalized welcome email.
Support follow-ups with context
- Trigger: support conversation closes.
- Assistant action: use /mcp/templates to select the appropriate follow-up template, render a preview with case details using /mcp/templates/:id/render, and then call /mcp/send.
- Result: consistent follow-up emails with ticket context and links.
Analytics-driven optimization for templates
- Trigger: product/marketing team wants to monitor template performance.
- Assistant action: query /mcp/stats for a date range to retrieve open/click rates for different template IDs.
- Result: data informs A/B tests or template revisions.

Tips and Troubleshooting

Ensure your SendGrid API key has the necessary scopes (Mail Send, Templates Read).
Use ALLOWLISTED_DOMAINS (or similar configuration) to prevent the server from sending to arbitrary addresses in untrusted deployments.
For local development, use a sandbox/test SendGrid account or the sandbox_mode feature to avoid sending real emails.
Check logs and the /health endpoint if the assistant reports connection problems.

If you need deeper customization (e.g., attachments, CC/BCC, advanced metrics), extend the server handlers to call the appropriate SendGrid API endpoints and expose additional MCP routes.

SendGrid MCP Server for Email Templates and Analytics