SendGrid MCP server

The SendGrid MCP server provides access to SendGrid's Marketing API, enabling you to manage contacts, create email lists, send campaigns, and work with email templates through a user-friendly Model Context Protocol interface.

Installation

To install the SendGrid MCP server:

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

Configuration

Getting Your API Key

1. Log in to your SendGrid account
2. Navigate to Settings > API Keys
3. Create a new API key with full access permissions
4. Save this key securely - SendGrid will only show it once

Setting Up the MCP Server

Add your SendGrid API key to the Cline MCP settings file within VSCode's settings:

{
  "mcpServers": {
    "sendgrid": {
      "command": "node",
      "args": ["/path/to/sendgrid-mcp/build/index.js"],
      "env": {
        "SENDGRID_API_KEY": "your-api-key-here"
      },
      "disabled": false,
      "autoApprove": [
        "list_contacts",
        "list_contact_lists",
        "list_templates",
        "list_single_sends",
        "get_single_send",
        "list_verified_senders",
        "list_suppression_groups",
        "get_stats",
        "validate_email"
      ]
    }
  }
}

Note: Tools that modify data (like sending emails or creating contacts) require approval before execution for safety reasons.

Available Tools

Contact Management

Listing Contacts

List all contacts in your SendGrid account:

// No parameters required

Adding a Contact

Add a contact to your SendGrid marketing contacts:

{
  email: string;           // Required: Contact email address
  first_name?: string;     // Optional: Contact first name
  last_name?: string;      // Optional: Contact last name
  custom_fields?: object;  // Optional: Custom field values
}

Deleting Contacts

Delete contacts from your SendGrid account:

{
  emails: string[];  // Required: Array of email addresses to delete
}

Getting Contacts by List

Get all contacts in a specific list:

{
  list_id: string;  // Required: ID of the contact list
}

List Management

Listing Contact Lists

List all contact lists in your account:

// No parameters required

Creating a Contact List

Create a new contact list:

{
  name: string;  // Required: Name of the contact list
}

Deleting a List

Delete a contact list:

{
  list_id: string;  // Required: ID of the contact list to delete
}

Adding Contacts to a List

Add contacts to an existing list:

{
  list_id: string;    // Required: ID of the contact list
  emails: string[];   // Required: Array of email addresses to add
}

Removing Contacts from a List

Remove contacts from a list without deleting them:

{
  list_id: string;    // Required: ID of the contact list
  emails: string[];   // Required: Array of email addresses to remove
}

Email Sending

Sending an Individual Email

Send an email through SendGrid:

{
  to: string;                     // Required: Recipient email address
  subject: string;                // Required: Email subject line
  text: string;                   // Required: Plain text content
  from: string;                   // Required: Verified sender email address
  html?: string;                  // Optional: HTML content
  template_id?: string;           // Optional: Dynamic template ID
  dynamic_template_data?: object; // Optional: Template variables
}

Sending to a List

Send an email to an entire contact list using Single Sends:

{
  name: string;                     // Required: Name of the single send
  list_ids: string[];               // Required: Array of list IDs to send to
  subject: string;                  // Required: Email subject line
  html_content: string;             // Required: HTML content
  plain_content: string;            // Required: Plain text content
  sender_id: number;                // Required: ID of the verified sender
  suppression_group_id?: number;    // Required if custom_unsubscribe_url not provided
  custom_unsubscribe_url?: string;  // Required if suppression_group_id not provided
}

Template Management

This server supports dynamic templates only (not legacy templates).

Creating a Template

Create a new dynamic email template:

{
  name: string;           // Required: Name of the template
  subject: string;        // Required: Default subject line
  html_content: string;   // Required: HTML content with handlebars syntax
  plain_content: string;  // Required: Plain text content with handlebars syntax
}

Listing Templates

List all dynamic email templates:

// No parameters required

Getting a Template

Retrieve a template by ID:

{
  template_id: string;  // Required: ID of the template to retrieve
}

Deleting a Template

Delete a dynamic template:

{
  template_id: string;  // Required: ID of the template to delete
}

Additional Tools

Getting Email Statistics

Get SendGrid email statistics:

{
  start_date: string;                        // Required: Start date (YYYY-MM-DD)
  end_date?: string;                         // Optional: End date (YYYY-MM-DD)
  aggregated_by?: 'day' | 'week' | 'month';  // Optional: Aggregation period
}

Validating an Email

Validate an email address:

{
  email: string;  // Required: Email address to validate
}

Listing Verified Senders

List all verified sender identities:

// No parameters required

Listing Suppression Groups

List all unsubscribe groups:

// No parameters required

Important Usage Notes

• When sending emails to lists, you must provide either a suppression_group_id or custom_unsubscribe_url to comply with email regulations
• Sender email addresses must be verified with SendGrid before they can be used for sending
• Templates support handlebars syntax (e.g., {{variable_name}}) for personalization
• The SendGrid API is "eventually consistent" - data changes may not appear immediately after being made

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.