READMEmaster

SendGrid MCP Server

A Model Context Protocol (MCP) server implementation that provides email sending capabilities using the SendGrid API. Built with Deno and TypeScript.

Features

🚀 MCP Integration: Full Model Context Protocol server implementation
📧 Email Sending: Send emails via SendGrid API with both text and HTML content
🔒 Security: Input validation, HTML sanitization, and secure API key handling
✅ Validation: Comprehensive input validation using Zod schemas
🧪 Testing: Complete test suite with mocking capabilities
🦕 Deno Native: Built specifically for the Deno runtime

Prerequisites

Deno: Install Deno from deno.land
SendGrid Account: Sign up at sendgrid.com
SendGrid API Key: Create an API key with "Mail Send > Full Access" permissions
Verified Sender: Configure a verified sender identity in SendGrid

Installation

Option 1: From JSR (Recommended)

# Install from JSR
deno add jsr:@cong/sendgrid-mcp

# Or use directly without installation
deno run --allow-env --allow-net --allow-read jsr:@cong/sendgrid-mcp

Option 2: From Source

Clone this repository:

git clone <repository-url>
cd sendgrid-mcp

Set up your SendGrid configuration:

export SENDGRID_API_KEY="your-sendgrid-api-key"
export SENDGRID_FROM_EMAIL="sender@yourdomain.com"

Or create a .env file:

SENDGRID_API_KEY=your-sendgrid-api-key
SENDGRID_FROM_EMAIL=sender@yourdomain.com

Usage

Running the Server

Start the MCP server:

deno task start

Or with development mode (auto-restart on changes):

deno task dev

Running Tests

Execute the test suite:

deno task test

Direct Execution

You can also run the server directly:

deno run --allow-env --allow-net --allow-read main.ts

Development & Debugging

For development and debugging, you can use the MCP Inspector:

# Install MCP Inspector globally
npm install -g @modelcontextprotocol/inspector

# Run the server with MCP Inspector
npx @modelcontextprotocol/inspector deno run --allow-env --allow-net --allow-read main.ts

This will start a web interface at http://localhost:5173 where you can:

Test the send_email tool interactively
View server logs and debug information
Inspect tool schemas and responses
Debug MCP protocol communication

MCP Tool: send_email

The server provides a single MCP tool called send_email with the following schema:

Parameters

Parameter	Type	Required	Description
`to`	string (email)	Yes	Recipient email address
`subject`	string	Yes	Email subject line
`text`	string	No*	Plain text email content
`html`	string	No*	HTML email content

*Note: Either text or html (or both) must be provided. The from address is now configured server-side via the SENDGRID_FROM_EMAIL environment variable.

Example Usage

{
  "name": "send_email",
  "arguments": {
    "to": "recipient@example.com",
    "subject": "Welcome to our service!",
    "text": "Welcome! Thanks for signing up.",
    "html": "<h1>Welcome!</h1><p>Thanks for signing up.</p>"
  }
}

Response Format

Success Response:

{
  "content": [
    {
      "type": "text",
      "text": "Email sent successfully! Status: 202, Message ID: abc123def456"
    }
  ]
}

Error Response:

{
  "content": [
    {
      "type": "text",
      "text": "Validation error: to: Invalid recipient email address"
    }
  ],
  "isError": true
}

Security Features

Input Validation

Email address format validation using Zod schemas
Required field validation
Content requirement validation (text or HTML must be provided)

HTML Sanitization

The server automatically sanitizes HTML content using DOMPurify to prevent XSS attacks. This provides comprehensive protection against malicious HTML content while preserving safe formatting tags.

API Key Security

API key loaded from environment variables only
No hardcoded credentials in source code
API key validation at server startup
Error messages never expose API key information

Configuration

Environment Variables

Variable	Required	Description
`SENDGRID_API_KEY`	Yes	Your SendGrid API key with Mail Send permissions
`SENDGRID_FROM_EMAIL`	Yes	Verified sender email address for all outgoing emails

Deno Permissions

The server requires the following Deno permissions:

--allow-env: To read environment variables
--allow-net: To make HTTP requests to SendGrid API

Project Structure

sendgrid-mcp/
├── main.ts           # Main server implementation
├── main_test.ts      # Comprehensive test suite
├── deno.json         # Deno configuration and dependencies
├── README.md         # This documentation
└── .env              # Environment variables (optional, for development)

Dependencies

@modelcontextprotocol/sdk: MCP TypeScript SDK
@sendgrid/mail: SendGrid's Node.js email library
zod: TypeScript-first schema validation
@std/assert: Deno standard library assertions
@std/dotenv: Environment variable loading
dompurify: Secure HTML sanitization library

Error Handling

The server handles various error scenarios:

Validation Errors: Invalid email formats, missing required fields
SendGrid API Errors: Authentication failures, rate limits, invalid recipients
Network Errors: Connection timeouts, DNS resolution failures
Configuration Errors: Missing API key, invalid environment setup

All errors are returned in a structured format without exposing sensitive information.

Development

Adding New Features

Modify the server class in main.ts
Add corresponding tests in main_test.ts
Update this README if needed
Run tests to ensure everything works

Testing Strategy

The test suite covers:

Input validation with various edge cases
HTML sanitization functionality
Error handling scenarios
Schema validation
Mock SendGrid API responses

SendGrid Setup

Create Account: Sign up at sendgrid.com
Enable 2FA: Enable two-factor authentication for security
Create API Key:
- Go to Settings > API Keys
- Create a new API key with "Mail Send > Full Access" permissions
- Save the key securely
Verify Sender:
- Go to Settings > Sender Authentication
- Verify your sender email address or domain
- Use verified addresses in the from field

Claude Desktop Integration

Setup for Claude Desktop

Install the MCP Server: Choose one of the installation methods above
Configure Claude Desktop: Add the following configuration to your Claude Desktop MCP settings file:

For macOS:

# Location: ~/Library/Application Support/Claude/claude_desktop_config.json

For Windows:

# Location: %APPDATA%/Claude/claude_desktop_config.json

Configuration Example:

{
  "mcpServers": {
    "sendgrid": {
      "command": "deno",
      "args": [
        "run",
        "--allow-env",
        "--allow-net",
        "--allow-read",
        "jsr:@cong/sendgrid-mcp"
      ],
      "env": {
        "SENDGRID_API_KEY": "your-sendgrid-api-key-here",
        "SENDGRID_FROM_EMAIL": "your-verified-sender@yourdomain.com"
      }
    }
  }
}

Alternative: Using Local Installation

If you've cloned the repository locally:

{
  "mcpServers": {
    "sendgrid": {
      "command": "deno",
      "args": [
        "run",
        "--allow-env",
        "--allow-net",
        "--allow-read",
        "/path/to/sendgrid-mcp/main.ts"
      ],
      "env": {
        "SENDGRID_API_KEY": "your-sendgrid-api-key-here",
        "SENDGRID_FROM_EMAIL": "your-verified-sender@yourdomain.com"
      }
    }
  }
}

Using with Claude Desktop

Once configured, restart Claude Desktop. You'll now have access to the send_email tool:

Example Usage in Claude:

You: "Send a welcome email to new-user@example.com with the subject 'Welcome to Our Platform!' and include both a text and HTML version."

Claude: I'll send that welcome email for you using the SendGrid MCP server.

Using send_email tool:
{
  "to": "new-user@example.com",
  "subject": "Welcome to Our Platform!",
  "text": "Welcome to our platform! We're excited to have you on board. If you have any questions, please don't hesitate to reach out to our support team.",
  "html": "<h1>Welcome to Our Platform!</h1><p>We're excited to have you on board.</p><p>If you have any questions, please don't hesitate to reach out to our support team.</p>"
}

Claude: ✅ Email sent successfully! Status: 202, Message ID: abc123def456

Features Available to Claude:

Send Text Emails: Plain text email content
Send HTML Emails: Rich formatted email content with HTML
Automatic Sanitization: HTML content is automatically sanitized for security
Validation: Email addresses and content are validated before sending
Error Handling: Clear error messages for troubleshooting

Security Notes for Claude Desktop

Environment Variables: Store sensitive information like API keys in the environment configuration, not in conversation history
Verified Senders: Only emails from your verified SendGrid sender address will be sent
HTML Sanitization: All HTML content is automatically sanitized to prevent XSS attacks
No API Key Exposure: API keys are never exposed in error messages or logs

Troubleshooting Claude Desktop Integration

Server Not Starting:

Verify Deno is installed and accessible from your PATH
Check that the configuration file syntax is valid JSON
Ensure all required environment variables are set

Permission Errors:

Verify the Deno flags include --allow-env, --allow-net, and --allow-read
Check that Claude Desktop has permission to execute Deno

Email Not Sending:

Verify your SendGrid API key has "Mail Send" permissions
Ensure the sender email address is verified with SendGrid
Check the Claude Desktop logs for detailed error messages
Use MCP Inspector to test the tool directly: npx @modelcontextprotocol/inspector deno run --allow-env --allow-net --allow-read main.ts

Troubleshooting

Common Issues

Server won't start:

Check that SENDGRID_API_KEY is set
Verify the API key has correct permissions
Ensure Deno has network permissions

Email not sending:

Verify the from address is verified with SendGrid
Check SendGrid API key permissions
Review SendGrid activity logs for detailed error information

Permission errors:

Ensure you're running with --allow-env --allow-net flags
Check that the API key environment variable is accessible

Debug Mode

For additional debugging, you can modify the error handling in main.ts to log more detailed information during development.

Using MCP Inspector for Debugging

The MCP Inspector provides a powerful web interface for testing and debugging:

# Set up environment variables
export SENDGRID_API_KEY="your-sendgrid-api-key"
export SENDGRID_FROM_EMAIL="your-verified-sender@domain.com"

# Start the inspector
npx @modelcontextprotocol/inspector deno run --allow-env --allow-net --allow-read main.ts

The inspector allows you to:

Test Tools: Send test emails with different parameters
View Schemas: Inspect the tool's input/output schemas
Monitor Logs: See real-time server logs and errors
Debug Protocol: Examine MCP protocol messages
Validate Setup: Ensure your environment is configured correctly

Publishing to JSR

This package is published to the JavaScript Registry (JSR). To publish a new version:

Update Version: Update the version in deno.json
Test Package: Run the publish check
```
deno task publish:check
```
Publish: Publish to JSR
```
deno task publish
```

Development Workflow

# Install dependencies and run tests
deno task test

# Check for publishing issues
deno task publish:check

# Start development server
deno task dev

Contributing

Fork the repository
Create a feature branch
Add tests for new functionality
Ensure all tests pass
Run deno task publish:check to verify package structure
Submit a pull request

License

This project is open source. Please check the repository for license details.

Support

For issues and questions:

Check the troubleshooting section above
Review SendGrid documentation
Check MCP documentation at modelcontextprotocol.io
Open an issue in the repository

Built with ❤️ using Deno and TypeScript