Content
# SendGrid MCP Server
A production-ready **Model Context Protocol (MCP) Server** for SendGrid email services, built with **FastMCP 2.0**. This server enables AI models like Claude, GPT, and others to send emails, manage contacts, and interact with SendGrid's powerful email platform.
## 🚀 Features
- **📧 Email Management**: Send HTML/text emails with templates and attachments
- **👥 Contact Management**: Add contacts and manage mailing lists
- **🔐 Secure Authentication**: Bearer token authentication with fallback support
- **⚡ Rate Limiting**: Built-in API rate limiting to prevent abuse
- **🛡️ Production Ready**: Comprehensive error handling and logging
- **🔧 Easy Configuration**: Environment-based configuration management
## 📋 Requirements
- Python 3.8+
- SendGrid API Key
- FastMCP 2.0
## 🛠️ Installation
1. **Clone the repository:**
```bash
git clone https://github.com/FINCH285/SendGrid-MCP-Server.git
cd SendGrid-MCP-Server
```
2. **Install dependencies:**
```bash
pip install -r requirements.txt
```
3. **Set up environment variables:**
```bash
cp .env.example .env
```
Edit `.env` with your SendGrid configuration:
```env
SENDGRID_API_KEY=your_sendgrid_api_key_here
DEFAULT_FROM_EMAIL=your-verified-email@example.com
DEFAULT_FROM_NAME=Your Name
DEFAULT_TEMPLATE_ID=your-template-id
RATE_LIMIT=10
DEBUG=false
```
## 🚀 Usage
### Running the Server
```bash
python main.py
```
The server will start and listen for MCP connections via STDIO.
### Available Tools
#### Email Tools
- **`send_email`** - Send HTML/text emails to multiple recipients
- **`get_template_info`** - Fetch SendGrid template details
- **`send_template_email`** - Send emails using dynamic templates
#### Contact Tools
- **`add_contact`** - Add/update contacts with custom fields
- **`get_contact_lists`** - Retrieve all contact lists
## 🔧 Configuration
### Authentication
The server supports two authentication methods:
1. **Environment Variable**: Set `SENDGRID_API_KEY` in your `.env` file
2. **Bearer Token**: Pass API key via Authorization header in MCP requests
## 📚 SendGrid Configuration example
```python
{
"mcpServers": {
"sendgrid-mcp": {
"command": "python",
"args": ["/path/to/your/project/main.py"],
"cwd": "/path/to/your/project",
"disabled": false,
"env": {
"SENDGRID_API_KEY": "SG.your-actual-api-key-here"
}
}
}
}
```
For Windows users, use paths like:
```json
"args": ["C:\\Users\\YourUsername\\project-folder\\main.py"]
"cwd": "C:\\Users\\YourUsername\\project-folder"
```
For macOS/Linux users, use paths like:
```json
"args": ["/Users/yourusername/project-folder/main.py"]
"cwd": "/Users/yourusername/project-folder"
```
Key configuration elements:
- "sendgrid-mcp": The server name/identifier (customizable)
- args: Specifies the path to your main.py file
- cwd: Sets the working directory to your project folder
- disabled: Set to false to enable the server
- env: Contains your SendGrid API key (replace with your actual key starting with "SG.")
## 🏗️ Architecture
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ AI Model │◄──►│ FastMCP │◄──►│ SendGrid │
│ (Claude/GPT) │ │ Server │ │ API │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
│ MCP Protocol │ HTTP/REST │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Tools Layer │ │ Auth Layer │ │ Config Layer │
│ • email_tools │ │ • Bearer Token │ │ • Environment │
│ • contact_tools │ │ • API Key Auth │ │ • Rate Limits │
└─────────────────┘ └─────────────────┘ └─────────────────┘
```
## 🤝 Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🆘 Support
- **Issues**: [GitHub Issues](https://github.com/FINCH285/SendGrid-MCP-Server/issues)
- **SendGrid Documentation**: [SendGrid API Docs](https://docs.sendgrid.com/)
- **FastMCP Documentation**: [FastMCP Docs](https://github.com/jlowin/fastmcp)
## 🙏 Acknowledgments
- [SendGrid](https://sendgrid.com/) for their excellent email API
- [FastMCP](https://github.com/jlowin/fastmcp) for the MCP framework
- [Anthropic](https://anthropic.com/) for the Model Context Protocol specification
