{"id":"b7105a4a-c4d0-469a-b0ca-836b4cbc86ba","slug":"garethcull-sendgrid-mcp","kind":"mcp","name":"sendgrid-mcp","summary":"An open source Sendgrid MCP server that helps marketing teams pull email stats and save html templates to sendgrid using AI Models. Built in Flask with Python.","owner":"garethcull","repoUrl":"https://github.com/garethcull/sendgrid-mcp","license":"MIT","licenseTier":"permissive","trust":"community","stars":2,"match":null,"fewStars":true,"format":"mcp","createdAt":"2025-11-24T19:08:44.000Z","addedAt":"2026-10-21T16:21:01.734Z","logoUrl":"https://avatars.githubusercontent.com/u/3453253?u=e0510f8d5a155a081433dd58111e4e97ba006c40&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["browser-web","productivity","communication"],"tags":[],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-22T21:57:12.130Z","sample":false,"url":"https://conduits.dev/tools/garethcull-sendgrid-mcp","language":"Python","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# SendGrid MCP Server\n\nA Model Context Protocol (MCP) server that exposes SendGrid Email Management and Reporting tools as MCP-compatible endpoints. This MCP Server provides endpoints for automated interaction with SendGrid — allowing AI Assistants, MCP Clients such as OpenAI’s Responses API, Cursor, or the prototypr.ai MCP Client to read, create, analyze, and manage email templates or metrics through natural language.\n\nThis server is built using Flask and can be deployed to Google Cloud Run or any environment that supports Python-based web services.\n\nIt was originally designed as part of prototypr.ai's Studio product, to help streamline email marketing creation. When you connect this MCP in prototypr.ai Studio you can import any dynamic email template to the Studio canvas, make changes with leading models such as Gemini 3 Pro and save these changes back into your Sendgrid account.\n\nYou can also use prototypr.ai Chat to pull email related stats from your Sendgrid account.\n\nEven though this MCP Tool was built for prototypr.ai, it is compatable with other MCP remote clients. Feel free to try them out as well!\n\n# MCP Features\n\nThis SendGrid MCP Server exposes multiple tools through the MCP protocol:\n\n- list_email_templates – Fetches a list of available SendGrid dynamic email templates.\n- get_html_template_by_id – Retrieves the HTML body for a specific template ID.\n- save_email_html_template – Saves a new or updated HTML email template to SendGrid.\n- get_aggregate_email_stats – Aggregates email performance metrics (delivered, opens, clicks, etc.) by day, week, or month and makes available through chat.\n\nAll endpoints are protected. A valid MCP_TOKEN must be provided as a shared secret for authorization.\n\n\n# MCP Architecture\n\nThis MCP server contains two files:\n1. app.py - main python file which authenticates and delegates requests to mcp_helper.py\n2. mcp_helper.py - Contains all SendGrid-specific logic, including email template management and statistical report generation.\n\n### app.py\nFlask app with POST /mcp\nHandles JSON-RPC notifications by returning 204 No Content\nDelegates to mcp_helper for MCP method logic\n\n### mcp_helper.py\nhandle_request routes initialize, tools/list, tools/call\nContains business logic for interacting with the SendGrid REST API and formatting results for LLM or MCP consumption.\n\n\n# Endpoints and Protocol\nJSON-RPC MCP (preferred by this server)\nPOST /mcp\nContent-Type: application/json\nAuth: Authorization: Bearer MCP_TOKEN\nMethods\ninitialize → returns protocolVersion, serverInfo, capabilities\ntools/list → returns tools with inputSchema (camelCase)\ntools/call → returns result with content array\nnotifications/initialized → must NOT return a JSON-RPC body; respond 204\n\n# Environment Variables\n\nThis MCP server has environment variables that need to be set in order for it to work. They are:\n\nMCP_TOKEN – Authorization token for all incoming requests.\nSENDGRID_API_KEY – The SendGrid API key with sufficient permissions to read and write templates, as well as fetch analytics.\n\n\n# Local Setup\nPython environment\n\n## Create and activate a virtual environment\npython3 -m venv .venv\nsource .venv/bin/activate\n\n## Install dependencies\npip install -r requirements.txt\n\nEnvironment variables (example)\nexport MCP_TOKEN=\"your-shared-token\"\nexport SENDGRID_API_KEY=\"your-sendgrid-api-key\"\n\n\n## Run locally\nexport FLASK_APP=app.py\nflask run --host 0.0.0.0 --port 8080\n\n## Quick JSON-RPC Tests\nUse Python requests to verify initialize, notifications/initialized, tools/list, and tools/call. Replace the base URL and token.\n\n```python\nimport requests, json\n\nBASE = \"https://<your-cloud-run-host>/mcp\"\nAUTH = \"Bearer <your-mcp-token>\"\n\ndef rpc(method, params, id_):\n    payload = {\"jsonrpc\":\"2.0\",\"id\":id_, \"method\":method, \"params\":params}\n    r = requests.post(BASE, headers={\"Authorization\": AUTH, \"Content-Type\":\"application/json\"}, data=json.dumps(payload))\n    print(method, r.status_code)\n    print(r.text[:600])\n    return r\n\n# 1) initialize\nrpc(\"initialize\", {}, \"1\")\n\n# 2) tools/list\nrpc(\"tools/list\", {}, \"2\")\n\n# 3) tools/call\nrpc(\"tools/call\", {\n    \"name\":\"get_aggregate_email_stats\",\n  \"arguments\":{\"start_date\":\"2025-01-01\",\"end_date\":\"2025-01-31\",\"aggregated_by\":\"day\"}\n}, \"3\")\n```\n\n# OpenAI Responses API Tool Configuration\n\nThis MCP tool was initially designed to use the OpenAI Responses API. For more details about OpenAI's Responses API and MCP, please check out this cookbook: \nhttps://cookbook.openai.com/examples/mcp/mcp_tool_guide\n\nConfigure an MCP tool in your Responses API request. Point server_url to your /mcp endpoint and include the Authorization header.\n\n```python\ntools = [\n  {\n    \"type\": \"mcp\",\n    \"server_label\": \"sendgrid-mcp\",\n    \"server_url\": \"https://<your-cloud-run-host>/mcp\",\n    \"headers\": { \"Authorization\": \"Bearer <your-mcp-token>\" },\n    \"require_approval\": \"never\"\n  }\n]\n```\n\n\n\n# Adding New Tools\nNew MCP tools can be registered by extending handle_tools_list() in mcp_helper.py, and defining logic in handle_tool_call().\n\nExample:\n\n\n\n```python\n{\n  \"name\": \"list_email_templates\",\n  \"description\": \"Fetches available SendGrid templates\",\n  \"inputSchema\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"list_type\": {\"type\":\"string\",\"description\":\"dynamic or legacy\"}\n    },\n    \"required\": [\"list_type\"]\n  }\n}\n```\n\nThen handle it inside handle_tool_call() as:\n\n```python\nif tool_name == \"list_email_templates\":\n    data = list_email_templates(arguments)\n    return {\"content\":[{\"type\":\"text\",\"text\":str(data)}]}\n```\n\n# Security Considerations\n\nAll /mcp routes require a valid MCP_TOKEN for authorization.\nEnsure the SENDGRID_API_KEY used has the correct API permissions (Mail Send, Marketing, and Stats API scopes).\nAvoid logging or exposing email data publicly.\n\n# Deploying to Google Cloud Run\n\nThis MCP server is designed for easy deployment to Google Cloud Run.\n\n1. Containerize your code using a lightweight Python base image.\n2. Set environment variables within the Cloud Run service.\n3. Ensure your service is configured with an Authorization header for secure access.\n\nHere is a link to an article that helped me deploy this MCP Server to Google Cloud Run: \nhttps://docs.cloud.google.com/run/docs/quickstarts/build-and-deploy/deploy-python-service\n\n\n# License\nMIT\n\n# Contributions & Support\nFeedback, issues and PRs welcome. Due to bandwidth constraints, I can't offer any timelines for free updates to this codebase. \n\nIf you need help customizing this MCP server, I'm available for paid consulting and freelance projects. Feel free to reach out and connect w/ me on LinkedIn:\nhttps://www.linkedin.com/in/garethcull/\n\nThanks for checking out the SendGrid MCP Server! This tool helps developers and AI agents automate SendGrid analytics, reporting, and template management in minutes.\n\nHappy Emailing!\n"}