# SendGrid MCP Server

A Python MCP (Model Context Protocol) server that lets an AI assistant send
email and manage contacts through [SendGrid](https://sendgrid.com)'s Web API v3.

## Tools

| Tool | Description |
| --- | --- |
| `send_email` | Send plain/HTML email to one or more recipients |
| `get_template_info` | Inspect a dynamic template's structure |
| `send_template_email` | Send via a dynamic template with substitution data |
| `add_contact` | Add/update a marketing contact (processed asynchronously by SendGrid) |
| `search_contacts` | Search contacts with a bounded SGQL query |
| `get_contact_lists` | List the named marketing contact lists |
| `authenticate_domain` | Start Domain Authentication for a new sending domain, returns DNS records to add |
| `list_domain_authentications` | List domains and their validation status |
| `validate_domain_authentication` | Re-check DNS after records are added |
| `delete_domain_authentication` | Remove a domain authentication |

## Setup

1. Create a virtual environment and install dependencies:

   ```bash
   python -m venv venv
   source venv/bin/activate   # Windows: venv\Scripts\activate
   pip install -r requirements.txt
   ```

2. Copy `.env.example` to `.env` and fill in your SendGrid API key
   (Settings > API Keys in the SendGrid dashboard) and default sender:

   ```bash
   cp .env.example .env
   ```

3. Verify your sender email under Settings > Sender Authentication in
   SendGrid before sending -- unverified senders will be rejected.

4. (Optional) Create a dynamic template under Email API > Dynamic
   Templates and set `DEFAULT_TEMPLATE_ID` in `.env`.

## Running

```bash
python main.py
```

This runs the server over stdio, the transport MCP clients like Claude
Desktop expect for a local subprocess.

## Verifying it works

```bash
python smoke_test.py
```

Lists the registered tools and makes one live call against your SendGrid
account. For interactive schema/tool inspection:

```bash
npx @modelcontextprotocol/inspector python main.py
```

## Connecting to Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "sendgrid-mcp": {
      "command": "python",
      "args": ["/path/to/twilio-sendgrid-mcp/main.py"],
      "cwd": "/path/to/twilio-sendgrid-mcp",
      "env": {
        "SENDGRID_API_KEY": "SG.your-actual-api-key-here"
      }
    }
  }
}
```

Restart Claude Desktop afterward. If a tool call fails, check
`~/Library/Logs/Claude/mcp*.log` (macOS) for the server's stderr output.