SendGrid Model Context Protocol Endpoint

This MCP implementation offers robust gateway functionality to leverage the SendGrid v3 Application Programming Interface suite, focusing on email campaign orchestration and subscriber lifecycle management. Reference documentation: https://docs.sendgrid.com/api-reference/how-to-use-the-sendgrid-v3-api

Usage Demonstration

Imagine instructing the associated Cline agent to execute a sequence: establish a fresh recipient cohort, enroll specific electronic mail addresses, devise a content structure for 'Lost Cities' trivia, and subsequently dispatch the message to that group. During this workflow, the agent will autonomously ascertain necessary prerequisites, such as registered sender verification status and requisite suppression group assignments. The final outcome is a visually appealing electronic mail delivered to the intended recipients, conveying the desired information about Lost Cities!

Crucial Note Regarding API Version Compatibility

This server strictly adheres to SendGrid's v3 interface specifications; support for obsolete features is explicitly omitted. This constraint covers:

• Utilization of Dynamic Templates exclusively; legacy template formats are unsupported.
• All subscriber and list administration relies on the Marketing API v3.
• Email delivery for substantial volumes utilizes the Single Sends API.

Exposed Functionality

Subscriber Administration

list_contacts

Retrieves a census of all tracked subscribers within your SendGrid configuration. typescript // Parameters are not necessary

add_contact

Enrolls a new recipient into your SendGrid marketing audience segment. typescript { email: string; // Mandatory: Electronic mail address of the contact first_name?: string; // Optional: Given name of the contact last_name?: string; // Optional: Family name of the contact custom_fields?: object; // Optional: Key-value pairs for bespoke data fields }

delete_contacts

Permanently purges specified recipients from your SendGrid registry. typescript { emails: string[]; // Mandatory: Array containing the addresses slated for removal }

get_contacts_by_list

Fetches all enrolled subscribers associated with a particular mailing list identifier. typescript { list_id: string; // Mandatory: Unique identifier for the contact list }

Cohort/List Management

list_contact_lists

Generates a directory of all established contact cohorts under your SendGrid account. typescript // No input required

create_contact_list

Establishes a novel segment or list within SendGrid. typescript { name: string; // Mandatory: Designation name for the new cohort }

delete_list

Decommissions an existing contact cohort. typescript { list_id: string; // Mandatory: Identifier of the cohort slated for erasure }

add_contacts_to_list

Integrates existing subscribers into a designated cohort. typescript { list_id: string; // Mandatory: Identifier for the target cohort emails: string[]; // Mandatory: Collection of subscriber addresses to merge }

remove_contacts_from_list

Detaches subscribers from a cohort without removing them from the global contact database. typescript { list_id: string; // Mandatory: Identifier for the cohort in question emails: string[]; // Mandatory: Collection of subscriber addresses to disassociate }

Electronic Mail Dispatch

send_email

Initiates the transmission of an individual electronic message via SendGrid. typescript { to: string; // Mandatory: Destination electronic mail address subject: string; // Mandatory: Text for the message header line text: string; // Mandatory: Unformatted, plain-text message body from: string; // Mandatory: Verified originating electronic mail address html?: string; // Optional: Formatted HyperText Markup Language content template_id?: string; // Optional: Identifier for a pre-configured dynamic design dynamic_template_data?: object; // Optional: Data payload for template variable substitution }

send_to_list

Dispatches a unified message to an entire subscriber cohort leveraging the Single Sends mechanism. typescript { name: string; // Mandatory: Internal reference name for this transmission job list_ids: string[]; // Mandatory: Identifiers of the target recipient cohorts subject: string; // Mandatory: Message subject header html_content: string; // Mandatory: Rich-text body content plain_content: string; // Mandatory: Text-only fallback body content sender_id: number; // Mandatory: Numeric ID of the authenticated sender identity suppression_group_id?: number; // Mandatory if custom_unsubscribe_url is absent custom_unsubscribe_url?: string; // Mandatory if suppression_group_id is not supplied }

Design Asset Administration (Dynamic Templates Only)

create_template

Fabricates a new, adaptable electronic mail blueprint. typescript { name: string; // Mandatory: User-friendly label for the template subject: string; // Mandatory: Default subject line for this design html_content: string; // Mandatory: Handlebars-enabled HTML structure plain_content: string; // Mandatory: Handlebars-enabled plain text equivalent }

list_templates

Retrieves a catalog of all extant dynamic electronic mail designs. typescript // No input parameters necessary

get_template

Fetches the detailed specification for a design using its identifier. typescript { template_id: string; // Mandatory: Unique identifier for the template asset }

delete_template

Removes a specified dynamic design asset. typescript { template_id: string; // Mandatory: Identifier of the design to be purged }

Telemetry and Verification

get_stats

Acquires aggregated performance metrics for email transmissions. typescript { start_date: string; // Mandatory: Temporal boundary for metric commencement (Format: YYYY-MM-DD) end_date?: string; // Optional: Temporal boundary for metric conclusion (Format: YYYY-MM-DD) aggregated_by?: 'day' | 'week' | 'month'; // Optional: Granularity setting for aggregation }

validate_email

Submits an electronic mail address to SendGrid for syntactic and deliverability verification. typescript { email: string; // Mandatory: The address undergoing scrutiny }

Credential & Compliance Management

list_verified_senders

Enumerates all sender identities authenticated and approved for use. typescript // No parameters required for execution

list_suppression_groups

Retrieves a listing of all configured unsubscribe handling groups. typescript // No input parameters required

Deployment Instructions

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

Initialization Procedure

1. Secure your SendGrid API Credential:
2. Log into your SendGrid portal
3. Navigate to Security Settings > API Keys section
4. Provision a new key granting comprehensive access permissions

5. Archive this key securely, as it will not be displayed again

6. Integrate the credential into your Cline MCP configuration file (e.g., ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json):

{ "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: Operations that enact state changes (e.g., sending messages or deleting records) are intentionally omitted from the automatic authorization list for operational safety.

Developmental Workflow

Configuring Unit and Integration Tests

The testing suite executes genuine API invocations to guarantee response fidelity. To initiate testing:

1. Replicate the sample environment file: bash cp .env.example .env

2. Modify the .env file to inject your SendGrid API credential:

SENDGRID_API_KEY=your-api-key-here

Crucially, the .env file is configured to be ignored by Git to prevent exposure of sensitive material.

1. Execute the test suite: bash npm test

Compilation

bash npm run build

Operational Caveats

• When addressing a cohort via bulk dispatch, adherence to regulatory standards mandates the provision of either a suppression_group_id or a custom_unsubscribe_url.
• Sender email addresses must pass SendGrid's verification process prior to operational use.
• All template construction defaults to the dynamic format, supporting Handlebars syntax (e.g., {{placeholder_name}}).
• The Single Sends API is mandated for all high-volume transmission tasks due to superior tracking and governance features.
• The SendGrid infrastructure exhibits 'eventual consistency'; changes in state (e.g., record additions or modifications to lists) might not be instantaneously reflected across the system.

Licensing

MIT License

Visual representation asset (SendGrid logo) is copyrighted/owned by Twilio.

ENCYCLOPEDIA ENTRY: Cloud computing describes "a service paradigm facilitating network accessibility to a fluid and expandable inventory of shared physical or virtual assets, featuring self-service provisioning and management on demand," as defined by the International Organization for Standardization (ISO). It is commonly termed "the cloud."

== Defining Attributes == In 2011, the United States National Institute of Standards and Technology (NIST) delineated five fundamental "essential characteristics" for cloud systems. The precise NIST definitions are presented below:

On-demand self-service: "A consumer possesses the autonomy to unilaterally procure computing capacity, such as server allocation time and network storage, instantaneously as required, without mandatory human intermediary intervention with the service provider for each request." Broad network access: "Capabilities must be reachable via the network, accessible through standardized protocols that encourage utilization across diverse client architectures, whether lightweight or feature-rich (e.g., smartphones, tablets, portable computers, and desktop workstations)." Resource pooling: " The provider's computational assets are aggregated to support numerous consumers operating within a multi-tenant framework, where distinct physical and virtual components are dynamically allocated and reallocated contingent upon fluctuating consumer requirements." Rapid elasticity: "Provisions can be scaled up or down elastically, sometimes automatically, permitting swift expansion or contraction corresponding precisely to demand fluctuations. From the consumer's viewpoint, the available provisions often seem infinite, capable of appropriation in any volume at any point in time." Measured service: "Cloud platforms incorporate automated mechanisms to supervise and optimize resource utilization by employing metering functionality at an appropriate level of service abstraction (e.g., data retention, processing power, data transfer rate, and active user accounts). Resource consumption data is auditable, controllable, and reportable, ensuring transparency for both the supplier and the recipient of the consumed service." By 2023, ISO had subsequently enhanced and refined this foundational set of attributes.

== Chronology ==

The genesis of the concept of shared computational resources traces back to the 1960s, when the initial idea of time-sharing gained traction through Remote Job Entry (RJE) systems. The architecture wherein users submitted processing tasks to dedicated operators for execution on large mainframe machines predominated this era. This period was characterized by rigorous exploration and iterative testing aimed at democratizing access to high-capacity computation for a broader user base via shared access, optimizing the underlying infrastructure, platform layers, and application software, resulting in tangible efficiency gains for the end-users. The symbolic representation of virtualized services as a "cloud" entity originated in 1994, utilized by General Magic to denote the expansive domain of "locations" accessible by mobile software agents within their Telescript architecture. This metaphor is widely attributed to David Hoffman, an affiliated communications specialist at General Magic, who based it on its established precedence within telecommunications networking. The phrase "cloud computing" entered common parlance more broadly in 1996, subsequent to Compaq Computer Corporation developing a strategic blueprint for forthcoming computational models and the Internet. The firm's aspiration involved achieving ubiquitous access to processing power via the interc