SendGrid MCP Server

1# SendGrid MCP Server
2 
3A 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.
4 
5## Installation
6 
7```bash
8npm install -g sendgrid-mcp
9```
10 
11Then configure with your preferred MCP client (see [configuration examples](#mcp-client-configuration) below).
12 
13## Supported MCP Clients
14 
15✅ **Claude Desktop** - Official desktop app
16✅ **Claude Code** - Official CLI tool
17✅ **Cline** - VS Code extension
18✅ **Zed Editor** - Modern code editor
19✅ **Continue** - VS Code autopilot
20✅ **Any MCP-compatible client**
21 
22## Features
23 
24- **Marketing Automations**: Create and manage email automation workflows
25- **Single Send Campaigns**: Manage one-time email campaigns with detailed performance tracking
26- **Contact Management**: Complete CRUD operations for contacts with advanced search and bulk operations
27- **Email Statistics & Analytics**: Multi-dimensional performance analysis across browsers, devices, geography, and email providers with 13-month historical data
28- **Dynamic Segment Management**: Create, update, and delete contact segments with complex filtering criteria that automatically refresh
29- **Dynamic Template Management**: Create, manage, and version HTML email templates with Handlebars support for personalization
30- **Custom Fields Management**: Define and manage additional contact data fields for enhanced targeting
31- **Mail Sending**: Send transactional emails via SendGrid with full personalization support  
32- **Sender Identity Management**: Manage verified sender identities with authentication tracking
33- **Suppression Lists**: Manage bounces, spam reports, and unsubscribes for deliverability optimization
34- **Account Settings**: Access account details and configuration management
35- **Browser Integration**: Quick links to SendGrid web interface for visual operations
36- **Read-Only Safety Mode**: Secure operation mode prevents accidental data modification while maintaining full analytics access
37 
38## Quick Start
39 
40### 1. Installation
41 
42Install the SendGrid MCP server globally via npm:
43 
44```bash
45npm install -g sendgrid-mcp
46```
47 
48### 2. Get Your SendGrid API Key
49 
501. Go to [SendGrid API Keys](https://app.sendgrid.com/settings/api_keys)
512. Click "Create API Key"
523. Choose "Full Access" or select specific permissions
534. Copy the generated key (starts with `SG.`)
54 
55### 3. Configure Your MCP Client
56 
57Add the server to your MCP client configuration (see detailed setup instructions below).
58 
59That's it! The server will run automatically when your MCP client starts.
60 
61## MCP Client Configuration
62 
63### Claude Desktop
64 
65The official Claude desktop application with native MCP support.
66 
67**Configuration File Locations:**
68- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
69- **Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
70 
71**Configuration:**
72```json
73{
74  "mcpServers": {
75    "sendgrid": {
76      "command": "sendgrid-mcp",
77      "env": {
78        "SENDGRID_API_KEY": "SG.your_api_key_here",
79        "READ_ONLY": "true"
80      }
81    }
82  }
83}
84```
85 
86**Optional Configuration:**
87```json
88{
89  "mcpServers": {
90    "sendgrid": {
91      "command": "sendgrid-mcp",
92      "env": {
93        "SENDGRID_API_KEY": "SG.your_api_key_here",
94        "READ_ONLY": "false",
95        "LOG_LEVEL": "info",
96        "REQUEST_TIMEOUT": "30000"
97      }
98    }
99  }
100}
101```
102 
103**After configuration:**
1041. Save the file
1052. Restart Claude Desktop
1063. The SendGrid MCP server will be available in Claude
107 
108---
109 
110### Claude Code (CLI)
111 
112Claude's official command-line interface with MCP support.
113 
114**Installation:**
115```bash
116npm install -g @anthropic-ai/claude-code
117```
118 
119**Configuration File Location:**
120- **All platforms**: `~/.claude/config.json`
121 
122**Configuration:**
123```json
124{
125  "mcpServers": {
126    "sendgrid": {
127      "command": "sendgrid-mcp",
128      "env": {
129        "SENDGRID_API_KEY": "SG.your_api_key_here",
130        "READ_ONLY": "true"
131      }
132    }
133  }
134}
135```
136 
137**Usage:**
138```bash
139# Start Claude Code with SendGrid MCP
140claude
141 
142# The SendGrid tools will be automatically available
143# Ask Claude: "List my SendGrid automations"
144```
145 
146---
147 
148### Cline (VS Code Extension)
149 
150Popular VS Code extension with MCP support.
151 
152**Installation:**
1531. Install the Cline extension from VS Code marketplace
1542. Open Cline settings
155 
156**Configuration File:**
157- Open VS Code Settings
158- Search for "Cline: MCP Settings"
159- Edit the MCP configuration JSON
160 
161**Configuration:**
162```json
163{
164  "mcpServers": {
165    "sendgrid": {
166      "command": "sendgrid-mcp",
167      "env": {
168        "SENDGRID_API_KEY": "SG.your_api_key_here",
169        "READ_ONLY": "true"
170      }
171    }
172  }
173}
174```
175 
176---
177 
178### Zed Editor
179 
180Modern code editor with built-in AI and MCP support.
181 
182**Configuration File Location:**
183- **macOS/Linux**: `~/.config/zed/settings.json`
184- **Windows**: `%APPDATA%/Zed/settings.json`
185 
186**Configuration:**
187```json
188{
189  "context_servers": {
190    "sendgrid-mcp": {
191      "command": "sendgrid-mcp",
192      "env": {
193        "SENDGRID_API_KEY": "SG.your_api_key_here",
194        "READ_ONLY": "true"
195      }
196    }
197  }
198}
199```
200 
201---
202 
203### Continue (VS Code Extension)
204 
205Open-source autopilot for VS Code with MCP support.
206 
207**Configuration File Location:**
208- **All platforms**: `~/.continue/config.json`
209 
210**Configuration:**
211```json
212{
213  "experimental": {
214    "modelContextProtocolServers": [
215      {
216        "command": "sendgrid-mcp",
217        "env": {
218          "SENDGRID_API_KEY": "SG.your_api_key_here",
219          "READ_ONLY": "true"
220        }
221      }
222    ]
223  }
224}
225```
226 
227---
228 
229### Generic MCP Client
230 
231For any MCP-compatible client not listed above:
232 
233**Command Line:**
234```bash
235# With environment variables
236SENDGRID_API_KEY="SG.your_api_key_here" READ_ONLY="true" sendgrid-mcp
237```
238 
239**Configuration Template:**
240```json
241{
242  "command": "sendgrid-mcp",
243  "env": {
244    "SENDGRID_API_KEY": "SG.your_api_key_here",
245    "READ_ONLY": "true"
246  }
247}
248```
249 
250---
251 
252## Building from Source (Advanced)
253 
254Only needed if you want to modify the server or contribute to development.
255 
256```bash
257# Clone the repository
258git clone https://github.com/your-username/sendgrid-mcp.git
259cd sendgrid-mcp
260 
261# Install dependencies
262npm install
263 
264# Build the server
265npm run build
266 
267# Link for local testing
268npm link
269```
270 
271**Using Local Build in MCP Clients:**
272```json
273{
274  "mcpServers": {
275    "sendgrid": {
276      "command": "node",
277      "args": ["/absolute/path/to/sendgrid-mcp/build/index.js"],
278      "env": {
279        "SENDGRID_API_KEY": "SG.your_api_key_here",
280        "READ_ONLY": "true"
281      }
282    }
283  }
284}
285```
286 
287## Environment Variables
288 
289| Variable | Required | Description | Default |
290|----------|----------|-------------|---------|
291| `SENDGRID_API_KEY` | ✅ | Your SendGrid API key (starts with SG.) | - |
292| `MCP_SERVER_NAME` | ❌ | Server name for identification | `sendgrid-mcp` |
293| `MCP_SERVER_VERSION` | ❌ | Server version | `1.0.0` |
294| `LOG_LEVEL` | ❌ | Logging level (debug, info, warn, error) | `info` |
295| `REQUEST_TIMEOUT` | ❌ | API request timeout in milliseconds | `30000` |
296| `READ_ONLY` | ❌ | Enable read-only mode (true/false) | `true` |
297 
298## Read-Only Mode
299 
300By 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.
301 
302### How Read-Only Mode Works
303 
304When `READ_ONLY=true` (default):
305- **All tools are registered** and visible to the AI assistant
306- **Non-mutating operations** work normally (list, get, search, open browser links)
307- **Mutating operations** are blocked with a clear error message: 
308  ```
309  ❌ Operation blocked: Server is running in READ_ONLY mode. Set READ_ONLY=false in your environment to enable write operations.
310  ```
311 
312### Read-Only Safe Operations
313 
314These operations work normally when `READ_ONLY=true`:
315 
316**Contact Operations:**
317- `list_contacts`, `get_contact`, `search_contacts`, `search_contacts_by_emails`
318 
319**List Operations:**  
320- `list_email_lists`, `list_segments`
321 
322**Field Operations:**
323- `list_custom_fields`
324 
325**Sender Operations:**
326- `list_senders`
327 
328**Campaign & Automation Operations:**
329- `list_automations`, `list_single_sends`
330- `open_automation_creator`, `open_automation_editor`
331- `open_single_send_creator`, `open_single_send_stats`
332 
333**Utility Operations:**
334- `get_scopes`, `open_segment_creator`, `open_csv_uploader`
335 
336### Blocked Operations in Read-Only Mode
337 
338These operations are blocked when `READ_ONLY=true`:
339- `update_automation_settings`, `update_automation_step`, `delete_automation`
340- `create_contact`, `update_contact`, `delete_contact`
341- `create_contact_with_lists`, `remove_contact_from_lists`
342- `create_email_list`, `update_email_list`, `delete_email_list`
343- `create_custom_field`, `update_custom_field`, `delete_custom_field`
344- `create_sender`, `delete_sender`
345- `update_segment`, `delete_segment`
346- `create_template`, `update_template`, `delete_template`
347- `create_template_version`, `update_template_version`, `delete_template_version`
348- `create_html_template`
349- `send_mail`
350 
351### Full Access Mode
352 
353To enable **create, update, delete, and send operations**, set `READ_ONLY=false` in your `.env` file:
354 
355```bash
356READ_ONLY=false
357```
358 
359This will allow all mutating operations to execute normally while maintaining all read operations.
360 
361**⚠️ Security Note:** Only disable read-only mode if you need write access and trust the environment where the server is running.
362 
363## Available Tools
364 
365### Marketing Automations
366- `list_automations` - List all marketing automations with metadata
367- `get_automation` - Get detailed information about a specific automation
368- `update_automation_settings` - Update automation-level settings (name, status)
369- `update_automation_step` - Update individual step settings (status, wait time)
370- `delete_automation` - Permanently delete an automation
371- `open_automation_creator` - Open automation creator in browser
372- `open_automation_editor` - Open specific automation editor
373 
374### Single Send Campaigns
375- `list_single_sends` - List all single send campaigns with metadata
376- `open_single_send_creator` - Open campaign creator in browser for visual design
377- `open_single_send_stats` - View detailed campaign performance statistics
378 
379### Contact Management
380 
381#### Contact CRUD Operations
382- `list_contacts` - List all contacts with pagination and filtering
383- `get_contact` - Get detailed information about a specific contact
384- `create_contact` - Create new contacts with custom fields
385- `update_contact` - Update existing contact information and custom data
386- `delete_contact` - Delete contacts permanently with cleanup
387- `search_contacts` - Search for contacts using advanced query conditions
388- `search_contacts_by_emails` - Search for specific contacts by email addresses
389 
390#### List Management
391- `list_email_lists` - List all email lists
392- `create_email_list` - Create a new email list
393- `update_email_list` - Update email list properties
394- `delete_email_list` - Delete an email list
395- `create_contact_with_lists` - Create contacts and assign to lists
396- `remove_contact_from_lists` - Remove contacts from a specific list
397 
398#### Dynamic Segments & Custom Fields
399- `list_segments` - List dynamic segments with parent relationships and criteria
400- `open_segment_creator` - Open segment creator in browser for visual query building
401- `update_segment` - Update existing segment name or query criteria with real-time refresh
402- `delete_segment` - Delete an existing segment (contacts remain unaffected)
403- `list_custom_fields` - List custom field definitions with data types
404- `create_custom_field` - Create new custom fields (Text, Number, Date types)
405- `update_custom_field` - Update existing custom field definitions
406- `delete_custom_field` - Delete custom field definitions with data cleanup
407 
408#### Senders & Import
409- `list_senders` - List verified sender identities
410- `create_sender` - Create new sender identity
411- `delete_sender` - Delete a verified sender identity
412- `open_csv_uploader` - Open CSV upload interface
413 
414### Dynamic Email Templates
415 
416#### Template Management
417- `list_templates` - List all dynamic and legacy templates
418- `get_template` - Get details of a specific template including all versions
419- `create_template` - Create a new dynamic template
420- `update_template` - Update template name and settings
421- `delete_template` - Delete a template and all its versions
422 
423#### Template Version Management
424- `create_template_version` - Create a new version with HTML content and settings
425- `get_template_version` - Get details of a specific template version  
426- `update_template_version` - Update version content, subject, and settings
427- `delete_template_version` - Delete a specific template version
428 
429#### AI-Optimized Tools
430- `create_html_template` - Create complete template with HTML content in one step (perfect for AI agents)
431- `open_template_editor` - Open SendGrid's visual template editor in browser
432 
433**Template Features:**
434- Handlebars syntax support for dynamic content ({{variable}}, {{#each}}, {{#if}})
435- Responsive HTML design with CSS inline support
436- Version management (up to 300 versions per template)
437- Test data integration for preview
438- Plain text auto-generation
439 
440### Mail Sending
441- `send_mail` - Send transactional emails (supports templates with dynamic_template_data)
442- `get_scopes` - Get available API permission scopes
443 
444### Email Statistics & Analytics
445 
446#### Global Performance
447- `get_global_stats` - Retrieve overall email performance metrics
448- `get_stats_overview` - Get comprehensive statistics across multiple dimensions
449 
450#### Technology-Based Analytics  
451- `get_stats_by_browser` - Statistics broken down by browser type (Chrome, Firefox, Safari, etc.)
452- `get_stats_by_client_type` - Statistics by email client type (desktop, mobile, webmail)
453- `get_stats_by_device_type` - Statistics by device type (desktop, mobile, tablet)
454- `get_stats_by_mailbox_provider` - Statistics by mailbox provider (Gmail, Outlook, Yahoo, etc.)
455 
456#### Geographic & Segmentation Analytics
457- `get_stats_by_country` - Statistics by country and state/province
458- `get_category_stats` - Statistics for specific email categories (13-month history)
459- `get_subuser_stats` - Statistics for specific subuser accounts
460 
461**Key Metrics Tracked:**
462- Delivery rates, open rates, click-through rates
463- Bounce rates (hard/soft), spam reports, unsubscribes
464- Geographic performance, device preferences
465- Email client compatibility, browser rendering
466- Provider-specific deliverability (Gmail, Outlook, etc.)
467 
468## Tools Summary
469 
470**Total Tools: 59**
471 
472| Category | Tools | Read-Only | Mutable | Description |
473|----------|-------|-----------|---------|-------------|
474| **Marketing Automations** | 7 | 3 | 4 | Full automation management with CRUD operations |
475| **Single Send Campaigns** | 3 | 3 | 0 | List campaigns, open creator, view stats |
476| **Contact Management** | 8 | 5 | 3 | Full CRUD operations for contacts |
477| **Email List Management** | 4 | 1 | 3 | Create, list, update, delete email lists |
478| **Segment Management** | 4 | 2 | 2 | List, create, update, delete segments |
479| **Custom Fields** | 4 | 1 | 3 | Manage additional contact data fields |
480| **Sender Identities** | 3 | 1 | 2 | Manage verified sender identities |
481| **Contact Operations** | 3 | 0 | 3 | List operations, CSV import utilities |
482| **Dynamic Templates** | 11 | 3 | 8 | Create, manage, and version HTML email templates |
483| **Email Statistics** | 10 | 10 | 0 | Comprehensive analytics and reporting |
484| **Mail Sending** | 1 | 0 | 1 | Send transactional emails |
485| **Utilities** | 1 | 1 | 0 | API scopes and permissions |
486 
487### Statistics Tools Breakdown
488 
489The 10 statistics tools provide comprehensive email performance analytics:
490 
491- **Global Analytics**: Overall performance metrics and multi-dimensional overviews
492- **Technology Analytics**: Browser, email client, and device-specific performance  
493- **Geographic Analytics**: Country and regional performance analysis
494- **Provider Analytics**: Mailbox provider-specific metrics (Gmail, Outlook, Yahoo)
495- **Segmentation Analytics**: Category-based and subuser performance tracking
496 
497### Read-Only vs Mutable Operations
498 
499- **Read-Only Safe (28 tools)**: Always available, no data modification risk
500- **Mutable Operations (31 tools)**: Blocked when `READ_ONLY=true` for safety
501- **Statistics**: All 10 analytics tools are read-only by design
502- **Templates**: 8 mutable template operations for creation and management
503- **Automations**: 4 mutable operations for full automation lifecycle management
504 
505## Available Resources
506 
507- `sendgrid://automations` - Marketing automations data
508- `sendgrid://singlesends` - Single send campaigns data
509- `sendgrid://lists` - Email lists data
510- `sendgrid://contacts` - Contact segments data
511- `sendgrid://suppressions` - Suppression lists (bounces, spam, etc.)
512- `sendgrid://account` - Account profile information
513- `sendgrid://stats` - Global email statistics and performance metrics (30-day overview)
514- `sendgrid://stats/browsers` - Email statistics by browser type (7-day data)
515- `sendgrid://stats/devices` - Email statistics by device type (7-day data)
516- `sendgrid://stats/geography` - Email statistics by geographic location (7-day data)
517- `sendgrid://stats/providers` - Email statistics by mailbox provider (7-day data)
518 
519## Available Prompts
520 
521- `sendgrid_automation_help` - Get help with marketing automations
522- `sendgrid_campaign_help` - Get help with single send campaigns
523- `sendgrid_contacts_help` - Get help with comprehensive contact management
524- `sendgrid_list_management_help` - Get help with email list CRUD operations
525- `sendgrid_update_list_help` - Get help with updating/renaming email lists
526- `sendgrid_contact_crud_help` - Get help with contact create/read/update/delete operations
527- `sendgrid_custom_fields_help` - Get help with custom field definitions management
528- `sendgrid_segment_management_help` - Get help with managing dynamic contact segments
529- `sendgrid_sender_management_help` - Get help with sender identity management
530- `sendgrid_templates_help` - Get help with creating and managing dynamic email templates
531- `sendgrid_suppressions_help` - Get help with suppression lists
532- `sendgrid_settings_help` - Get help with account settings
533- `sendgrid_mail_send_help` - Get help with sending emails
534- `sendgrid_stats_help` - Get help with analyzing email performance and statistics
535 
536## Examples
537 
538📚 **For extensive examples and natural language prompts, see [EXAMPLE_PROMPTS.md](EXAMPLE_PROMPTS.md)**
539 
540The following are JSON-based tool examples. For natural language examples you can use with Claude, check the comprehensive examples file.
541 
542### Get Automation Details
543 
544```json
545{
546  "tool": "get_automation",
547  "arguments": {
548    "automation_id": "automation_id_here"
549  }
550}
551```
552 
553### Update Automation Settings (Name, Status)
554 
555```json
556{
557  "tool": "update_automation_settings",
558  "arguments": {
559    "automation_id": "automation_id_here",
560    "title": "New Automation Name",
561    "status": "active"
562  }
563}
564```
565 
566### Pause an Entire Automation
567 
568```json
569{
570  "tool": "update_automation_settings",
571  "arguments": {
572    "automation_id": "automation_id_here",
573    "status": "paused"
574  }
575}
576```
577 
578### Update Automation Step (Status, Wait Time)
579 
580```json
581{
582  "tool": "update_automation_step",
583  "arguments": {
584    "automation_id": "automation_id_here",
585    "step_id": "step_id_here",
586    "step_status": "active",
587    "wait_time": 1440
588  }
589}
590```
591 
592### Delete an Automation
593 
594```json
595{
596  "tool": "delete_automation",
597  "arguments": {
598    "automation_id": "automation_id_here"
599  }
600}
601```
602 
603### Send a Simple Email
604 
605```json
606{
607  "tool": "send_mail",
608  "arguments": {
609    "personalizations": [
610      {
611        "to": [{"email": "recipient@example.com", "name": "John Doe"}],
612        "subject": "Hello from SendGrid MCP!"
613      }
614    ],
615    "from": {"email": "sender@yourdomain.com", "name": "Your Name"},
616    "content": [
617      {
618        "type": "text/plain",
619        "value": "Hello! This email was sent via SendGrid MCP server."
620      }
621    ]
622  }
623}
624```
625 
626### Create a New Contact
627 
628```json
629{
630  "tool": "create_contact",
631  "arguments": {
632    "contacts": [
633      {
634        "email": "newuser@example.com",
635        "first_name": "Jane",
636        "last_name": "Smith"
637      }
638    ]
639  }
640}
641```
642 
643### Search for Contacts by Email
644 
645```json
646{
647  "tool": "search_contacts_by_emails",
648  "arguments": {
649    "emails": ["john@example.com", "jane@example.com"]
650  }
651}
652```
653 
654### Search Contacts with Query Conditions
655 
656```json
657{
658  "tool": "search_contacts",
659  "arguments": {
660    "query": "email LIKE '@example.com'",
661    "page_size": 10
662  }
663}
664```
665 
666### Update Contact Information
667 
668```json
669{
670  "tool": "update_contact",
671  "arguments": {
672    "contacts": [
673      {
674        "id": "contact_id_here",
675        "first_name": "John",
676        "last_name": "Updated"
677      }
678    ]
679  }
680}
681```
682 
683### Delete Contacts
684 
685```json
686{
687  "tool": "delete_contact",
688  "arguments": {
689    "contact_ids": ["contact_id_1", "contact_id_2"]
690  }
691}
692```
693 
694### Remove Contacts from a List
695 
696```json
697{
698  "tool": "remove_contact_from_lists",
699  "arguments": {
700    "list_id": "list_id_here",
701    "contact_ids": ["contact_id_1", "contact_id_2"]
702  }
703}
704```
705 
706### Delete a Sender Identity
707 
708```json
709{
710  "tool": "delete_sender",
711  "arguments": {
712    "sender_id": "sender_id_here"
713  }
714}
715```
716 
717### Update an Email List
718 
719```json
720{
721  "tool": "update_email_list",
722  "arguments": {
723    "list_id": "list_id_here",
724    "name": "Updated List Name"
725  }
726}
727```
728 
729### Delete an Email List
730 
731```json
732{
733  "tool": "delete_email_list",
734  "arguments": {
735    "list_id": "list_id_here"
736  }
737}
738```
739 
740### Create a Custom Field
741 
742```json
743{
744  "tool": "create_custom_field",
745  "arguments": {
746    "name": "customer_tier",
747    "field_type": "Text"
748  }
749}
750```
751 
752### Update a Custom Field
753 
754```json
755{
756  "tool": "update_custom_field",
757  "arguments": {
758    "field_id": "field_id_here",
759    "name": "customer_level"
760  }
761}
762```
763 
764### Delete a Custom Field
765 
766```json
767{
768  "tool": "delete_custom_field",
769  "arguments": {
770    "field_id": "field_id_here"
771  }
772}
773```
774 
775### List Email Lists
776 
777```json
778{
779  "tool": "list_email_lists",
780  "arguments": {
781    "page_size": 100
782  }
783}
784```
785 
786### Update a Segment
787 
788```json
789{
790  "tool": "update_segment",
791  "arguments": {
792    "segment_id": "segment_id_here",
793    "name": "Updated Segment Name"
794  }
795}
796```
797 
798### Update Segment Query Criteria
799 
800```json
801{
802  "tool": "update_segment",
803  "arguments": {
804    "segment_id": "segment_id_here",
805    "query_dsl": "{\"and\": [{\"field\": \"email\", \"value\": \"@example.com\", \"operator\": \"like\"}]}"
806  }
807}
808```
809 
810### Delete a Segment
811 
812```json
813{
814  "tool": "delete_segment",
815  "arguments": {
816    "segment_id": "segment_id_here"
817  }
818}
819```
820 
821### Get Global Email Statistics
822 
823```json
824{
825  "tool": "get_global_stats",
826  "arguments": {
827    "start_date": "2024-01-01",
828    "end_date": "2024-01-31",
829    "aggregated_by": "day"
830  }
831}
832```
833 
834### Get Statistics by Mailbox Provider
835 
836```json
837{
838  "tool": "get_stats_by_mailbox_provider",
839  "arguments": {
840    "start_date": "2024-01-01",
841    "end_date": "2024-01-07",
842    "aggregated_by": "day",
843    "mailbox_providers": "gmail.com,outlook.com,yahoo.com"
844  }
845}
846```
847 
848### Get Geographic Performance Statistics
849 
850```json
851{
852  "tool": "get_stats_by_country",
853  "arguments": {
854    "start_date": "2024-01-01",
855    "end_date": "2024-01-31",
856    "country": "US",
857    "aggregated_by": "week"
858  }
859}
860```
861 
862### Get Comprehensive Statistics Overview
863 
864```json
865{
866  "tool": "get_stats_overview",
867  "arguments": {
868    "start_date": "2024-01-01",
869    "end_date": "2024-01-07",
870    "aggregated_by": "day",
871    "include_subusers": false
872  }
873}
874```
875 
876### Create Complete HTML Template (AI-Optimized)
877 
878```json
879{
880  "tool": "create_html_template",
881  "arguments": {
882    "template_name": "Welcome Email",
883    "version_name": "Version 1.0",
884    "subject": "Welcome to {{companyName}}, {{firstName}}!",
885    "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><div style=\"background-color: #f5f5f5; padding: 20px; margin: 20px 0;\"><h2>Getting Started:</h2><ul><li>Complete your profile</li><li>Explore our features</li><li>Contact support if needed</li></ul></div><p>Best regards,<br>The {{companyName}} Team</p></body></html>",
886    "test_data": "{\"firstName\":\"John\",\"companyName\":\"Acme Corp\"}"
887  }
888}
889```
890 
891### Create Template Version with HTML Content
892 
893```json
894{
895  "tool": "create_template_version",
896  "arguments": {
897    "template_id": "your_template_id",
898    "name": "Newsletter v1.0",
899    "subject": "{{month}} Newsletter - {{companyName}}",
900    "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>",
901    "test_data": "{\"month\":\"January\",\"companyName\":\"Acme\",\"articles\":[{\"title\":\"Article 1\",\"summary\":\"Summary here\",\"link\":\"https://example.com\"}]}"
902  }
903}
904```
905 
906### Send Email Using Template
907 
908```json
909{
910  "tool": "send_mail",
911  "arguments": {
912    "personalizations": [
913      {
914        "to": [{"email": "user@example.com", "name": "John Doe"}],
915        "dynamic_template_data": {
916          "firstName": "John",
917          "companyName": "Acme Corp",
918          "orderNumber": "12345",
919          "items": [
920            {"name": "Product A", "price": "29.99"},
921            {"name": "Product B", "price": "19.99"}
922          ]
923        }
924      }
925    ],
926    "from": {"email": "noreply@yourcompany.com", "name": "Your Company"},
927    "template_id": "d-1234567890abcdef1234567890abcdef"
928  }
929}
930```
931 
932## NPM Package
933 
934The SendGrid MCP Server is distributed as an npm package for easy installation:
935 
936**Package**: [`sendgrid-mcp`](https://www.npmjs.com/package/sendgrid-mcp)
937 
938### Installation
939 
940**Recommended - Global Installation:**
941```bash
942npm install -g sendgrid-mcp
943```
944 
945**Alternative - Local Installation:**
946```bash
947npm install sendgrid-mcp
948npx sendgrid-mcp
949```
950 
951### Version Updates
952 
953To update to the latest version:
954```bash
955npm update -g sendgrid-mcp
956```
957 
958## Development & Contributing
959 
960This section is for developers who want to contribute to the SendGrid MCP server.
961 
962### Prerequisites
963 
964- Node.js 18+ and npm
965- SendGrid account with API key
966- Git
967 
968### Development Setup
969 
970```bash
971# Clone the repository
972git clone https://github.com/your-username/sendgrid-mcp.git
973cd sendgrid-mcp
974 
975# Install dependencies
976npm install
977 
978# Build the project
979npm run build
980 
981# Link for local development
982npm link
983 
984# Test the local build
985sendgrid-mcp
986```
987 
988### Project Structure
989 
990```
991src/
992├── index.ts                    # Main entry point
993├── shared/                     # Shared utilities
994│   ├── auth.ts                 # Authentication
995│   ├── api.ts                  # SendGrid API client
996│   ├── env.ts                  # Environment validation
997│   └── types.ts                # Shared types
998├── tools/                      # Tool definitions
999│   ├── automations.ts          # Automation tools (7 tools)
1000│   ├── campaigns.ts            # Campaign tools (3 tools)
1001│   ├── contacts.ts             # Contact tools (33 tools)
1002│   ├── mail.ts                 # Mail sending tools (2 tools)
1003│   ├── misc.ts                 # Miscellaneous tools (1 tool)
1004│   ├── stats.ts                # Statistics tools (10 tools)
1005│   └── templates.ts            # Template tools (11 tools)
1006├── resources/                  # Resource definitions
1007│   └── sendgrid.ts             # MCP resources
1008└── prompts/                    # Prompt definitions
1009    └── help.ts                 # Help prompts
1010```
1011 
1012### Adding New Tools
1013 
10141. Add tool definition to appropriate file in `src/tools/`
10152. Follow the existing pattern with config and handler
10163. Export from `src/tools/index.ts`
10174. Update README.md with new tool documentation
10185. Run `npm run build` to compile
1019 
1020### Available Scripts
1021 
1022- `npm run build` - Compile TypeScript to JavaScript
1023- `npm start` - Run the compiled server
1024- `npm test` - Run tests (if available)
1025 
1026### Testing Your Changes
1027 
1028```bash
1029# Build the project
1030npm run build
1031 
1032# Test with environment variables
1033SENDGRID_API_KEY="SG.your_key" READ_ONLY="true" node build/index.js
1034```
1035 
1036### Creating a Release
1037 
1038For maintainers only:
1039 
10401. Update version in `package.json`:
1041   ```bash
1042   npm version patch  # or minor, major
1043   ```
1044 
10452. Push changes and tags:
1046   ```bash
1047   git push && git push --tags
1048   ```
1049 
10503. Create GitHub release - this triggers automatic npm publishing via GitHub Actions
1051 
1052### Publishing Process
1053 
1054- **Automated**: GitHub Actions publishes to npm on release creation
1055- **Provenance**: All packages include provenance attestation for security
1056- **Versioning**: Follows semantic versioning (semver)
1057 
1058## Troubleshooting
1059 
1060### Common Issues
1061 
1062**1. Server Not Found / Command Not Found**
1063```
1064Error: sendgrid-mcp: command not found
1065```
1066 
1067**Solution:**
1068- Ensure you installed globally: `npm install -g sendgrid-mcp`
1069- Check npm global bin directory is in PATH: `npm config get prefix`
1070- Try reinstalling: `npm uninstall -g sendgrid-mcp && npm install -g sendgrid-mcp`
1071 
1072---
1073 
1074**2. Invalid API Key**
1075```
1076Error: SENDGRID_API_KEY must start with 'SG.'
1077```
1078 
1079**Solution:**
1080- Ensure your API key starts with `SG.`
1081- Verify you copied the complete key from SendGrid
1082- Check for extra spaces or quotes in your configuration
1083- Generate a new API key at [SendGrid API Keys](https://app.sendgrid.com/settings/api_keys)
1084 
1085---
1086 
1087**3. Permission Errors**
1088```
1089Error: 403 Forbidden
1090```
1091 
1092**Solution:**
1093- Your API key may not have sufficient permissions
1094- Create a new key with "Full Access" or required scopes
1095- Verify the key hasn't been revoked or expired
1096 
1097---
1098 
1099**4. Read-Only Mode Blocking Operations**
1100```
1101❌ Operation blocked: Server is running in READ_ONLY mode
1102```
1103 
1104**Solution:**
1105- This is intentional security protection
1106- To enable write operations, set `READ_ONLY: "false"` in your MCP client configuration
1107- Example:
1108  ```json
1109  {
1110    "env": {
1111      "SENDGRID_API_KEY": "SG.your_key",
1112      "READ_ONLY": "false"
1113    }
1114  }
1115  ```
1116 
1117---
1118 
1119**5. MCP Client Not Detecting Server**
1120 
1121**Solution:**
1122- Verify the configuration file location for your specific client
1123- Ensure JSON syntax is valid (no trailing commas, proper quotes)
1124- Restart your MCP client after configuration changes
1125- Check client logs for specific error messages
1126 
1127---
1128 
1129**6. Connection Timeout**
1130```
1131Error: Request timeout
1132```
1133 
1134**Solution:**
1135- Check your internet connection
1136- Increase timeout in configuration:
1137  ```json
1138  {
1139    "env": {
1140      "REQUEST_TIMEOUT": "60000"
1141    }
1142  }
1143  ```
1144- Verify SendGrid API is accessible (not blocked by firewall/proxy)
1145 
1146---
1147 
1148### Getting Help
1149 
1150- **Built-in Help**: Use help prompts in your MCP client (e.g., ask Claude: "help with sendgrid automations")
1151- **SendGrid API**: [Official API Documentation](https://docs.sendgrid.com/api-reference)
1152- **MCP Protocol**: [Model Context Protocol Docs](https://modelcontextprotocol.io/)
1153- **Issues**: Report bugs at the [GitHub repository](https://github.com/your-username/sendgrid-mcp/issues)
1154 
1155### Debug Mode
1156 
1157Enable detailed logging by setting the LOG_LEVEL:
1158 
1159```json
1160{
1161  "env": {
1162    "SENDGRID_API_KEY": "SG.your_key",
1163    "LOG_LEVEL": "debug"
1164  }
1165}
1166```
1167 
1168This will provide detailed information about API requests and responses.
1169 
1170## License
1171 
1172This project is licensed under the ISC License.
1173 
1174## Contributing
1175 
11761. Fork the repository
11772. Create a feature branch
11783. Make your changes
11794. Test thoroughly
11805. Submit a pull request
1181 
1182## Support
1183 
1184For issues related to:
1185- **SendGrid API**: Check [SendGrid Documentation](https://docs.sendgrid.com/)
1186- **MCP Protocol**: Check [Model Context Protocol](https://modelcontextprotocol.io/)
1187- **This Server**: Open an issue in this repository