SendGrid MCP

Servidor SendGrid MCP

Um servidor Model Context Protocol (MCP) que fornece acesso abrangente à API v3 do SendGrid para email marketing, operações de email transacional, gerenciamento de templates dinâmicos e análises detalhadas. Possui 154 ferramentas cobrindo todos os aspectos do gerenciamento de email e análise de desempenho.

Construído e mantido por um engenheiro do SendGrid, como um projeto independente — não é um produto oficial do SendGrid.

Consulte RELEASES.md para ver o que mudou na versão mais recente.

Recursos

• Automações de Marketing: Crie e gerencie fluxos de trabalho de automação de email
• Campanhas de Envio Único: Gerencie campanhas de email pontuais com rastreamento detalhado de desempenho
• Gerenciamento de Contatos: Operações CRUD completas para contatos com busca avançada e operações em lote
• Estatísticas e Análises de Email: Análise de desempenho multidimensional em navegadores, dispositivos, geografia e provedores de email com dados históricos de 13 meses
• Gerenciamento de Segmentos Dinâmicos: Crie, atualize e exclua segmentos de contatos com critérios de filtragem complexos que são atualizados automaticamente
• Gerenciamento de Templates Dinâmicos: Crie, gerencie e versione templates de email HTML com suporte a Handlebars para personalização
• Gerenciamento de Campos Personalizados: Defina e gerencie campos adicionais de dados de contato para segmentação aprimorada
• Envio de Email: Envie emails transacionais via SendGrid com suporte completo a personalização
• Gerenciamento de Identidade do Remetente: Gerencie identidades de remetente verificadas com rastreamento de autenticação
• Listas de Supressão: Gerencie rejeições, relatórios de spam e cancelamentos de inscrição para otimização de entregabilidade
• Configurações da Conta: Acesse detalhes da conta e gerenciamento de configuração
• Integração com Navegador: Links rápidos para a interface web do SendGrid para operações visuais
• Modo de Segurança Somente Leitura: Modo de operação seguro que previne modificação acidental de dados enquanto mantém acesso completo a análises

Clientes MCP Suportados

✅ Claude Desktop - Aplicativo desktop oficial ✅ Claude Code - Ferramenta CLI oficial ✅ Conectores personalizados Claude - via Streamable HTTP (consulte Instalar o servidor) ✅ OpenAI Responses API / Apps SDK - via Streamable HTTP ✅ MCP Market - Hospedado, implantação com um clique, sem necessidade de instalação (consulte Instalar o servidor) ✅ Cline - Extensão do VS Code ✅ Zed Editor - Editor de código moderno ✅ Continue - Autopiloto do VS Code ✅ Codex CLI - via Streamable HTTP ✅ Qualquer cliente compatível com MCP

Primeiros Passos

Siga estes passos em ordem — ao final, você terá o servidor instalado (ou implantado), sua chave de API do SendGrid configurada e seu cliente MCP conectado.

Este é o caminho real de solicitação, independentemente do cliente que você usar — alguns iniciam o servidor localmente via stdio, outros o acessam pela rede via Streamable HTTP (MCP Market, auto-hospedado), o que adiciona uma escolha de autenticação de cliente por cima:

                                ┌──────────┐
                                │  Client  │
                                └────┬─────┘
              ┌──────────────────────┴───────────────────┐
              │                                          │
           stdio (local subprocess)        HTTP (network)
              │               auth: none | token | oauth │
              │                                          │
              └──────────────────────┬───────────────────┘
                                     ▼
                           ┌────────────────────┐
                           │     MCP Server     │
                           │    (this repo)     │
                           └─────────┬──────────┘
                                     │  SENDGRID_API_KEY
                                     │  (always required, any transport)
                                     ▼
                           ┌────────────────────┐
                           │    SendGrid API    │
                           └────────────────────┘

SENDGRID_API_KEY é obrigatório independentemente do caminho que você escolher. READ_ONLY=true (o padrão) é uma barreira adicional dentro da caixa do Servidor MCP — ele bloqueia ferramentas de criar/atualizar/excluir/enviar uma vez que a solicitação já entrou, independentemente de qual ramo ela chegou. Consulte Variáveis de Ambiente para a lista completa do que você pode configurar.

1. Instalar o servidor

Instale-o localmente se seu cliente o inicia por conta própria, ou vá remoto se ele se conecta pela rede.

Local (stdio) — para Claude Desktop, Claude Code, Cline, Zed, Continue, ou qualquer cliente que execute o servidor como subprocesso:

npm install -g sendgrid-mcp

Isso instala o comando sendgrid-mcp globalmente, que seu cliente MCP iniciará como subprocesso. Requer Node.js 20+.

Remoto (HTTP) — nada para instalar localmente; escolha um:

export SENDGRID_API_KEY="SG.your_api_key_here"
export MCP_TRANSPORT=http
export MCP_AUTH_MODE=token
export MCP_AUTH_TOKEN="$(openssl rand -hex 32)"

sendgrid-mcp

export MCP_AUTH_MODE=oauth
export MCP_OAUTH_ISSUER="https://your-tenant.auth0.com"
export MCP_OAUTH_AUDIENCE="https://mcp.example.com"
export MCP_OAUTH_REQUIRED_SCOPES="sendgrid:read"
export MCP_PUBLIC_URL="https://mcp.example.com"

export MCP_OAUTH_ISSUER="https://YOUR_TENANT.auth0.com/"
export MCP_OAUTH_AUDIENCE="https://mcp.example.com"
export MCP_OAUTH_REQUIRED_SCOPES="sendgrid:read"

export MCP_OAUTH_ISSUER="https://YOUR_OKTA_DOMAIN/oauth2/YOUR_AUTH_SERVER_ID"
export MCP_OAUTH_AUDIENCE="api://sendgrid-mcp"
export MCP_OAUTH_REQUIRED_SCOPES="sendgrid:read"

export MCP_OAUTH_ISSUER="https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0"
export MCP_OAUTH_AUDIENCE="api://YOUR_CLIENT_ID"
export MCP_OAUTH_REQUIRED_SCOPES="sendgrid.read"

export TLS_KEY_FILE=/etc/ssl/private/mcp.key
export TLS_CERT_FILE=/etc/ssl/certs/mcp.crt
export TLS_CA_FILE=/etc/ssl/certs/chain.pem   # optional intermediates

export TRUST_PROXY=true
export MCP_PUBLIC_URL="https://mcp.example.com"

{
  "model": "gpt-5",
  "tools": [{
    "type": "mcp",
    "server_label": "sendgrid",
    "server_url": "https://mcp.example.com/mcp",
    "authorization": "ACCESS_TOKEN"
  }],
  "input": "List my SendGrid automations"
}

2. Obtenha sua chave de API do SendGrid

1. Vá para Chaves de API do SendGrid
2. Clique em "Create API Key"
3. Escolha "Full Access" ou selecione permissões específicas
4. Copie a chave gerada (começa com SG.)

3. Configure seu cliente MCP

https://link.mcpmarket.com/<your-username>/<your-server-name>/mcp

# Claude Code
claude mcp add --transport http sendgrid https://link.mcpmarket.com/<your-username>/<your-server-name>/mcp

# Codex CLI
codex mcp add sendgrid --url https://link.mcpmarket.com/<your-username>/<your-server-name>/mcp

{
  "mcpServers": {
    "sendgrid": {
      "command": "sendgrid-mcp",
      "env": {
        "SENDGRID_API_KEY": "SG.your_api_key_here",
        "READ_ONLY": "true"
      }
    }
  }
}

{
  "mcpServers": {
    "sendgrid": {
      "command": "sendgrid-mcp",
      "env": {
        "SENDGRID_API_KEY": "SG.your_api_key_here",
        "READ_ONLY": "false",
        "LOG_LEVEL": "info",
        "REQUEST_TIMEOUT": "30000"
      }
    }
  }
}

npm install -g @anthropic-ai/claude-code

{
  "mcpServers": {
    "sendgrid": {
      "command": "sendgrid-mcp",
      "env": {
        "SENDGRID_API_KEY": "SG.your_api_key_here",
        "READ_ONLY": "true"
      }
    }
  }
}

# Start Claude Code with SendGrid MCP
claude

# The SendGrid tools will be automatically available
# Ask Claude: "List my SendGrid automations"

{
  "mcpServers": {
    "sendgrid": {
      "command": "sendgrid-mcp",
      "env": {
        "SENDGRID_API_KEY": "SG.your_api_key_here",
        "READ_ONLY": "true"
      }
    }
  }
}

{
  "context_servers": {
    "sendgrid-mcp": {
      "command": "sendgrid-mcp",
      "env": {
        "SENDGRID_API_KEY": "SG.your_api_key_here",
        "READ_ONLY": "true"
      }
    }
  }
}

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "command": "sendgrid-mcp",
        "env": {
          "SENDGRID_API_KEY": "SG.your_api_key_here",
          "READ_ONLY": "true"
        }
      }
    ]
  }
}

# With environment variables
SENDGRID_API_KEY="SG.your_api_key_here" READ_ONLY="true" sendgrid-mcp

{
  "command": "sendgrid-mcp",
  "env": {
    "SENDGRID_API_KEY": "SG.your_api_key_here",
    "READ_ONLY": "true"
  }
}

Variáveis de Ambiente

O servidor é configurado inteiramente por meio de variáveis de ambiente. SENDGRID_API_KEY é a única obrigatória.

READ_ONLY tem como padrão true. Nesse modo, todas as ferramentas são registradas e visíveis, mas operações que criam, atualizam, excluem ou enviam são bloqueadas em tempo de execução com uma mensagem de erro clara — apenas ferramentas de listar/obter/buscar/abrir link no navegador realmente são executadas. Este é o padrão mais seguro enquanto você está se configurando. Consulte Modo Somente Leitura para a análise completa do que é bloqueado e defina READ_ONLY=false quando estiver pronto para permitir operações de gravação e envio.

Essas variáveis são definidas na configuração do seu cliente MCP (como um bloco env) — consulte Configurar seu cliente MCP. O modo HTTP auto-hospedado tem seu próprio conjunto de variáveis (transporte, autenticação, TLS) — consulte Instalar o servidor.

Modo Somente Leitura

{
  "env": {
    "SENDGRID_API_KEY": "SG.your_api_key_here",
    "READ_ONLY": "false"
  }
}

Ferramentas Disponíveis

O servidor expõe 154 ferramentas agrupadas em 22 categorias. Todas as ferramentas são registradas independentemente do modo READ_ONLY — consulte Modo Somente Leitura para saber quais são bloqueadas por padrão.

📚 Para prompts em linguagem natural que você pode dizer diretamente ao Claude, consulte EXAMPLE_PROMPTS.md. Os exemplos abaixo mostram as chamadas de ferramentas JSON subjacentes.

Resumo das Ferramentas

Chaves de API, Alertas, Colegas de Equipe e IPs Dedicados são deliberadamente somente leitura neste servidor, e o gerenciamento de SSO/certificados não é exposto — consulte Operações Intencionalmente Não Suportadas para saber o motivo.

Automações de Marketing

• list_automations - Listar todas as automações de marketing com metadados
• get_automation - Obter informações detalhadas sobre uma automação específica
• update_automation_settings - Atualizar configurações no nível da automação (nome, status)
• update_automation_step - Atualizar configurações de etapas individuais (status, tempo de espera)
• delete_automation - Excluir permanentemente uma automação
• open_automation_creator - Abrir o criador de automações no navegador
• open_automation_editor - Abrir o editor de uma automação específica

{
  "tool": "get_automation",
  "arguments": {
    "automation_id": "automation_id_here"
  }
}

{
  "tool": "update_automation_settings",
  "arguments": {
    "automation_id": "automation_id_here",
    "status": "paused"
  }
}

{
  "tool": "update_automation_step",
  "arguments": {
    "automation_id": "automation_id_here",
    "step_id": "step_id_here",
    "step_status": "active",
    "wait_time": 1440
  }
}

{
  "tool": "delete_automation",
  "arguments": {
    "automation_id": "automation_id_here"
  }
}

Campanhas de Envio Único

• list_single_sends - Listar todas as campanhas de envio único com metadados
• get_single_send - Recuperar conteúdo detalhado e configurações de uma campanha de envio único
• open_single_send_creator - Abrir o criador de campanhas no navegador para design visual
• open_single_send_stats - Visualizar estatísticas detalhadas de desempenho da campanha

{
  "tool": "get_single_send",
  "arguments": {
    "singlesend_id": "singlesend_id_here"
  }
}

Operações CRUD de Contatos

• list_contacts - Listar todos os contatos com paginação e filtros
• get_contact - Obter informações detalhadas sobre um contato específico
• create_contact - Criar novos contatos com campos personalizados
• update_contact - Atualizar informações de contatos existentes e dados personalizados
• delete_contact - Excluir contatos permanentemente com limpeza
• search_contacts - Buscar contatos usando condições de consulta avançadas
• search_contacts_by_emails - Buscar contatos específicos por endereços de e-mail

{
  "tool": "create_contact",
  "arguments": {
    "contacts": [
      {
        "email": "newuser@example.com",
        "first_name": "Jane",
        "last_name": "Smith"
      }
    ]
  }
}

{
  "tool": "search_contacts_by_emails",
  "arguments": {
    "emails": ["john@example.com", "jane@example.com"]
  }
}

{
  "tool": "search_contacts",
  "arguments": {
    "query": "email LIKE '@example.com'",
    "page_size": 10
  }
}

{
  "tool": "update_contact",
  "arguments": {
    "contacts": [
      {
        "id": "contact_id_here",
        "first_name": "John",
        "last_name": "Updated"
      }
    ]
  }
}

{
  "tool": "delete_contact",
  "arguments": {
    "contact_ids": ["contact_id_1", "contact_id_2"]
  }
}

Gerenciamento de Listas de E-mail

• list_email_lists - Listar todas as listas de e-mail
• create_email_list - Criar uma nova lista de e-mail
• update_email_list - Atualizar propriedades da lista de e-mail
• delete_email_list - Excluir uma lista de e-mail
• create_contact_with_lists - Criar contatos e atribuir a listas
• remove_contact_from_lists - Remover contatos de uma lista específica

{
  "tool": "list_email_lists",
  "arguments": {
    "page_size": 100
  }
}

{
  "tool": "update_email_list",
  "arguments": {
    "list_id": "list_id_here",
    "name": "Updated List Name"
  }
}

{
  "tool": "remove_contact_from_lists",
  "arguments": {
    "list_id": "list_id_here",
    "contact_ids": ["contact_id_1", "contact_id_2"]
  }
}

{
  "tool": "delete_email_list",
  "arguments": {
    "list_id": "list_id_here"
  }
}

Segmentos e Campos Personalizados

• list_segments - Listar segmentos dinâmicos com relacionamentos pai e critérios
• open_segment_creator - Abrir o criador de segmentos no navegador para construção visual de consultas
• update_segment - Atualizar nome ou critérios de consulta de um segmento existente com atualização em tempo real
• delete_segment - Excluir um segmento existente (os contatos permanecem inalterados)
• list_custom_fields - Listar definições de campos personalizados com tipos de dados
• create_custom_field - Criar novos campos personalizados (tipos Texto, Número, Data)
• update_custom_field - Atualizar definições de campos personalizados existentes
• delete_custom_field - Excluir definições de campos personalizados com limpeza de dados

{
  "tool": "update_segment",
  "arguments": {
    "segment_id": "segment_id_here",
    "name": "Updated Segment Name"
  }
}

{
  "tool": "update_segment",
  "arguments": {
    "segment_id": "segment_id_here",
    "query_dsl": "{\"and\": [{\"field\": \"email\", \"value\": \"@example.com\", \"operator\": \"like\"}]}"
  }
}

{
  "tool": "delete_segment",
  "arguments": {
    "segment_id": "segment_id_here"
  }
}

{
  "tool": "create_custom_field",
  "arguments": {
    "name": "customer_tier",
    "field_type": "Text"
  }
}

{
  "tool": "update_custom_field",
  "arguments": {
    "field_id": "field_id_here",
    "name": "customer_level"
  }
}

{
  "tool": "delete_custom_field",
  "arguments": {
    "field_id": "field_id_here"
  }
}

Remetentes e Importação

• list_senders - Listar identidades de remetente verificadas
• create_sender - Criar nova identidade de remetente
• delete_sender - Excluir uma identidade de remetente verificada
• open_csv_uploader - Abrir interface de upload de CSV

{
  "tool": "create_sender",
  "arguments": {
    "nickname": "Marketing Team",
    "from": { "email": "marketing@yourdomain.com", "name": "Your Company" },
    "reply_to": { "email": "replies@yourdomain.com", "name": "Your Company" },
    "address": "123 Main St",
    "city": "Denver",
    "state": "CO",
    "zip": "80202",
    "country": "United States"
  }
}

{
  "tool": "delete_sender",
  "arguments": {
    "sender_id": "sender_id_here"
  }
}

Modelos Dinâmicos

• list_templates - Listar todos os modelos dinâmicos e legados
• get_template - Obter detalhes de um modelo específico, incluindo todas as versões
• create_template - Criar um novo modelo dinâmico
• update_template - Atualizar nome e configurações do modelo
• delete_template - Excluir um modelo e todas as suas versões
• create_template_version - Criar uma nova versão com conteúdo HTML e configurações
• get_template_version - Obter detalhes de uma versão específica do modelo
• update_template_version - Atualizar conteúdo, assunto e configurações da versão
• delete_template_version - Excluir uma versão específica do modelo
• create_html_template - Criar modelo completo com conteúdo HTML em uma única etapa (perfeito para agentes de IA)
• open_template_editor - Abrir o editor visual de modelos do SendGrid no navegador

Os modelos suportam sintaxe Handlebars para conteúdo dinâmico ({{variable}}, {{#each}}, {{#if}}), HTML responsivo com CSS inline, até 300 versões por modelo, visualizações com dados de teste e geração automática de texto simples.

{
  "tool": "create_html_template",
  "arguments": {
    "template_name": "Welcome Email",
    "version_name": "Version 1.0",
    "subject": "Welcome to {{companyName}}, {{firstName}}!",
    "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></body></html>",
    "test_data": "{\"firstName\":\"John\",\"companyName\":\"Acme Corp\"}"
  }
}

{
  "tool": "create_template_version",
  "arguments": {
    "template_id": "your_template_id",
    "name": "Newsletter v1.0",
    "subject": "{{month}} Newsletter - {{companyName}}",
    "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>",
    "test_data": "{\"month\":\"January\",\"companyName\":\"Acme\",\"articles\":[{\"title\":\"Article 1\",\"summary\":\"Summary here\",\"link\":\"https://example.com\"}]}"
  }
}

Envio de E-mails

• send_mail - Enviar e-mails transacionais (suporta modelos com dados dinâmicos de modelo)

{
  "tool": "send_mail",
  "arguments": {
    "personalizations": [
      {
        "to": [{"email": "recipient@example.com", "name": "John Doe"}],
        "subject": "Hello from SendGrid MCP!"
      }
    ],
    "from": {"email": "sender@yourdomain.com", "name": "Your Name"},
    "content": [
      {
        "type": "text/plain",
        "value": "Hello! This email was sent via SendGrid MCP server."
      }
    ]
  }
}

{
  "tool": "send_mail",
  "arguments": {
    "personalizations": [
      {
        "to": [{"email": "user@example.com", "name": "John Doe"}],
        "dynamic_template_data": {
          "firstName": "John",
          "companyName": "Acme Corp",
          "orderNumber": "12345",
          "items": [
            {"name": "Product A", "price": "29.99"},
            {"name": "Product B", "price": "19.99"}
          ]
        }
      }
    ],
    "from": {"email": "noreply@yourcompany.com", "name": "Your Company"},
    "template_id": "d-1234567890abcdef1234567890abcdef"
  }
}

Estatísticas e Análises de E-mail

• get_global_stats - Recuperar métricas gerais de desempenho de e-mail
• get_stats_overview - Obter estatísticas abrangentes em múltiplas dimensões
• get_stats_by_browser - Estatísticas divididas por tipo de navegador (Chrome, Firefox, Safari, etc.)
• get_stats_by_client_type - Estatísticas por tipo de cliente de e-mail (desktop, mobile, webmail)
• get_stats_by_device_type - Estatísticas por tipo de dispositivo (desktop, mobile, tablet)
• get_stats_by_mailbox_provider - Estatísticas por provedor de caixa de correio (Gmail, Outlook, Yahoo, etc.)
• get_stats_by_country - Estatísticas por país e estado/província
• get_category_stats - Estatísticas para categorias específicas de e-mail (histórico de 13 meses)
• get_subuser_stats - Estatísticas para contas de subusuários específicos

Acompanha taxas de entrega, abertura e cliques; taxas de rejeição (hard/soft), relatórios de spam e cancelamentos de inscrição; desempenho geográfico e preferências de dispositivo; compatibilidade com clientes de e-mail e renderização em navegadores; e entregabilidade específica por provedor.

{
  "tool": "get_global_stats",
  "arguments": {
    "start_date": "2024-01-01",
    "end_date": "2024-01-31",
    "aggregated_by": "day"
  }
}

{
  "tool": "get_stats_by_mailbox_provider",
  "arguments": {
    "start_date": "2024-01-01",
    "end_date": "2024-01-07",
    "aggregated_by": "day",
    "mailbox_providers": "gmail.com,outlook.com,yahoo.com"
  }
}

{
  "tool": "get_stats_by_country",
  "arguments": {
    "start_date": "2024-01-01",
    "end_date": "2024-01-31",
    "country": "US",
    "aggregated_by": "week"
  }
}

{
  "tool": "get_stats_overview",
  "arguments": {
    "start_date": "2024-01-01",
    "end_date": "2024-01-07",
    "aggregated_by": "day",
    "include_subusers": false
  }
}

Utilitários

• get_scopes - Obter escopos de permissão de API disponíveis (sem argumentos)

Supressões

• list_suppression_groups - Listar todos os grupos de cancelamento de inscrição (supressão) na conta
• create_suppression_group - Criar um novo grupo de cancelamento de inscrição (supressão)
• get_suppression_group - Obter detalhes sobre um grupo específico de cancelamento de inscrição (supressão)
• update_suppression_group - Atualizar nome, descrição ou status padrão de um grupo de supressão existente
• delete_suppression_group - Excluir permanentemente um grupo de cancelamento de inscrição (supressão). Esta ação não pode ser desfeita.
• list_group_suppressions - Listar todos os endereços de e-mail que cancelaram a inscrição de um grupo de supressão específico
• add_group_suppressions - Adicionar um ou mais endereços de e-mail à lista de cancelamento de inscrição de um grupo de supressão específico
• remove_group_suppression - Remover um único endereço de e-mail da lista de cancelamento de inscrição de um grupo de supressão específico. Isso apenas repermite o envio de e-mails atribuídos à categoria deste grupo — não é um novo cancelamento global.
• list_global_suppressions - Listar endereços de e-mail na lista global de cancelamento de inscrição da conta, opcionalmente filtrados por intervalo de tempo
• add_global_suppression - Adicionar destinatários à lista global de cancelamento de inscrição da conta — eles pararão de receber todos os e-mails não transacionais desta conta
• get_global_suppression - Verificar se um endereço de e-mail específico está na lista global de cancelamento de inscrição da conta
• delete_global_suppression - Remover um endereço de e-mail da lista global de supressão da conta, efetivamente reinscrevendo-o para e-mails não transacionais
• list_bounces - Listar todos os endereços de e-mail que sofreram rejeição, opcionalmente filtrados por intervalo de tempo
• get_bounce - Obter evento(s) de rejeição registrados para um endereço de e-mail específico
• delete_bounce - Remover um registro de rejeição de um endereço de e-mail para que este endereço possa receber e-mails novamente
• list_blocks - Listar todos os endereços de e-mail atualmente na lista de bloqueios, opcionalmente filtrados por intervalo de tempo
• delete_block - Remover um endereço de e-mail da lista de bloqueios para que este endereço possa receber e-mails novamente
• list_spam_reports - Listar todos os endereços de e-mail que relataram e-mails como spam, opcionalmente filtrados por intervalo de tempo
• delete_spam_report - Remover um endereço de e-mail da lista de relatórios de spam para que este endereço possa receber e-mails novamente
• list_invalid_emails - Listar todos os endereços de e-mail marcados como inválidos, opcionalmente filtrados por intervalo de tempo
• delete_invalid_email - Remover um endereço de e-mail da lista de e-mails inválidos para que este endereço possa receber e-mails novamente

Autenticação de Domínio e Marca de Links

• list_authenticated_domains - Listar todos os domínios autenticados (whitelabel) configurados para envio de e-mails
• get_authenticated_domain - Obter informações detalhadas sobre um domínio autenticado específico, incluindo seus registros DNS
• create_authenticated_domain - Configurar autenticação de domínio (SPF/DKIM) para envio de e-mails a partir de um domínio personalizado
• update_authenticated_domain - Atualizar o SPF personalizado ou as configurações padrão de um domínio autenticado existente
• delete_authenticated_domain - Excluir permanentemente um domínio autenticado. Esta ação não pode ser desfeita.
• validate_authenticated_domain - Verificar se os registros DNS do domínio estão configurados corretamente para autenticação
• get_default_authenticated_domain - Obter o domínio autenticado atualmente definido como padrão para envio de e-mails
• list_branded_links - Listar todos os links com marca (link whitelabels) configurados para rastreamento de cliques
• get_branded_link - Obter informações detalhadas sobre um link com marca específico, incluindo seus registros DNS
• create_branded_link - Configurar rastreamento de links com marca (rastreamento de cliques através do domínio do remetente em vez de sendgrid.net)
• update_branded_link - Atualizar a configuração padrão de um link com marca existente
• delete_branded_link - Excluir permanentemente um link com marca. Esta ação não pode ser desfeita.
• validate_branded_link - Verificar se os registros DNS do link com marca estão configurados corretamente

Webhooks de Eventos e Parse de Entrada

• list_event_webhooks - Listar todas as configurações de Event Webhook na conta
• get_event_webhook - Obter a configuração de um Event Webhook específico por ID
• create_event_webhook - Cria um novo Event Webhook que envia via POST eventos de e-mail (entregues, rejeitados, abertos, clicados, etc.) para a URL fornecida
• update_event_webhook - Atualizar a configuração de um Event Webhook existente
• delete_event_webhook - Excluir permanentemente uma configuração de Event Webhook. Esta ação não pode ser desfeita.
• test_event_webhook - Envia um payload de evento de teste para a URL do webhook fornecida para verificar se está acessível e configurado corretamente
• list_inbound_parse_settings - Listar todas as configurações de webhook de Parse de Entrada na conta
• get_inbound_parse_setting - Obter a configuração do webhook de Parse de Entrada para um hostname específico
• create_inbound_parse_setting - Configura o parse de e-mails de entrada para que e-mails enviados ao hostname fornecido sejam enviados via POST para a URL fornecida
• update_inbound_parse_setting - Atualizar a configuração do webhook de Parse de Entrada para um hostname específico
• delete_inbound_parse_setting - Excluir permanentemente uma configuração de webhook de Parse de Entrada para um hostname. Esta ação não pode ser desfeita.
• get_inbound_parse_stats - Obter estatísticas sobre o número de e-mails de entrada analisados em um intervalo de datas

Configurações de Rastreamento

• get_tracking_settings - Recuperar todas as configurações de rastreamento (cliques, aberturas, inscrição, Google Analytics) em uma única chamada
• get_click_tracking_settings - Recuperar a configuração atual de rastreamento de cliques
• update_click_tracking_settings - Ativar ou desativar o rastreamento de cliques em links dentro de e-mails
• get_google_analytics_settings - Recuperar as configurações atuais de rastreamento do Google Analytics
• update_google_analytics_settings - Atualizar as configurações de rastreamento do Google Analytics, incluindo valores de campanha UTM, conteúdo, mídia, origem e termo
• get_open_tracking_settings - Recuperar a configuração atual de rastreamento de aberturas
• update_open_tracking_settings - Ativar ou desativar o rastreamento de aberturas, que insere um pixel invisível para registrar quando um e-mail é aberto
• get_subscription_tracking_settings - Recuperar as configurações atuais de rastreamento de inscrições
• update_subscription_tracking_settings - Atualizar as configurações de rastreamento de inscrições, incluindo conteúdo do link de cancelamento, página de destino, URL e tag de substituição

Configurações de E-mail

• get_all_mail_settings - Recuperar todas as configurações de e-mail (whitelist de endereços, purga de rejeições, rodapé, encaminhamento de rejeições, encaminhamento de spam, etc.) em uma única chamada
• get_address_whitelist_settings - Recuperar a configuração atual de whitelist de endereços, que controla quais endereços de e-mail ou domínios ignoram todas as listas de supressão
• update_address_whitelist_settings - Atualizar a configuração de whitelist de endereços que controla quais endereços de e-mail ou domínios ignoram todas as listas de supressão
• get_bounce_purge_settings - Recuperar a configuração atual de purga de rejeições, que purga automaticamente registros antigos de rejeição após um número configurado de dias
• update_bounce_purge_settings - Atualizar a configuração de purga de rejeições que purga automaticamente registros antigos de rejeição após um número configurado de dias
• get_footer_settings - Recuperar a configuração atual de rodapé, que anexa um rodapé a cada e-mail enviado
• update_footer_settings - Atualizar a configuração de rodapé que anexa um rodapé a cada e-mail enviado
• get_forward_bounce_settings - Recuperar a configuração atual de encaminhamento de rejeições, que encaminha notificações de rejeição para um endereço de e-mail fornecido
• update_forward_bounce_settings - Atualizar a configuração de encaminhamento de rejeições que encaminha notificações de rejeição para um endereço de e-mail fornecido
• get_forward_spam_settings - Recuperar a configuração atual de encaminhamento de spam, que encaminha notificações de relatórios de spam para um endereço de e-mail fornecido
• update_forward_spam_settings - Atualizar a configuração de encaminhamento de spam que encaminha notificações de relatórios de spam para um endereço de e-mail fornecido

Chaves de API (somente leitura)

• list_api_keys - Lista todas as chaves de API da conta (apenas nomes e IDs, não os valores secretos das chaves)
• get_api_key - Obtém detalhes de uma chave de API específica, incluindo seus escopos

Alertas (somente leitura)

• list_alerts - Lista todos os alertas de uso/estatísticas configurados na conta
• get_alert - Obtém detalhes de um alerta específico

Colegas de equipe (somente leitura)

• list_teammates - Lista todos os colegas de equipe (usuários) da conta
• get_teammate - Obtém detalhes de um colega de equipe específico, incluindo seus escopos de permissão
• list_pending_teammates - Lista convites pendentes de colegas de equipe que ainda não foram aceitos

IPs dedicados (somente leitura)

• list_ip_addresses - Lista todos os endereços IP atribuídos à conta
• get_ip_address - Obtém detalhes de um endereço IP específico, incluindo seu status de aquecimento e subusuários atribuídos
• list_assigned_ips - Lista todos os endereços IP atualmente atribuídos a um subusuário
• list_ip_pools - Lista todos os pools de IP da conta
• get_ip_pool - Obtém detalhes de um pool de IP específico, incluindo os endereços IP que ele contém
• get_remaining_ips - Obtém a quantidade e o custo de endereços IP dedicados adicionais disponíveis para compra
• list_ip_warmups - Lista todos os endereços IP atualmente em processo de aquecimento
• get_ip_warmup_status - Obtém o status de aquecimento de um endereço IP específico
• list_allowed_ips - Lista endereços IP autorizados a acessar a conta via API/UI (a lista de permissões de acesso)
• get_allowed_ip - Obtém detalhes de uma entrada específica na lista de permissões de acesso
• list_access_activity - Lista tentativas recentes de acesso à conta (logins/chamadas de API bem-sucedidos e bloqueados)

Biblioteca de Design

• list_designs - Lista todos os designs de e-mail personalizados na Biblioteca de Design
• create_design - Cria um novo design de e-mail personalizado na Biblioteca de Design a partir de HTML bruto
• get_design - Obtém detalhes de um design específico na Biblioteca de Design
• update_design - Atualiza o conteúdo ou os metadados de um design existente na Biblioteca de Design
• delete_design - Exclui permanentemente um design personalizado da Biblioteca de Design. Esta ação não pode ser desfeita.
• duplicate_design - Cria uma cópia de um design existente na Biblioteca de Design
• list_prebuilt_designs - Lista os modelos de design pré-fabricados integrados do SendGrid
• get_prebuilt_design - Obtém detalhes de um dos designs pré-fabricados integrados do SendGrid
• duplicate_prebuilt_design - Cria uma cópia editável de um dos designs pré-fabricados integrados do SendGrid

Validação de Endereço de E-mail

• validate_email - Verifica se um endereço de e-mail é válido e provavelmente entregável, usando a API de Validação de Endereço de E-mail do SendGrid (consome um crédito de validação cobrado por chamada)

Pesquisa de Mensagens

• search_email_activity - Pesquisa a atividade de mensagens enviadas usando a sintaxe de filtro SGQL do SendGrid (por exemplo, por destinatário, status ou assunto) — útil para solucionar problemas de por que um e-mail específico não foi entregue
• get_message_details - Obtém o histórico completo de eventos de entrega e detalhes de uma única mensagem enviada pelo seu ID de mensagem

Recursos Disponíveis

• sendgrid://automations - Dados de automações de marketing
• sendgrid://singlesends - Dados de campanhas de envio único
• sendgrid://lists - Dados de listas de e-mail
• sendgrid://contacts - Dados de segmentos de contatos
• sendgrid://suppressions - Listas de supressão (rejeições, spam, etc.)
• sendgrid://account - Informações do perfil da conta
• sendgrid://stats - Estatísticas globais de e-mail e métricas de desempenho (visão geral de 30 dias)
• sendgrid://stats/browsers - Estatísticas de e-mail por tipo de navegador (dados de 7 dias)
• sendgrid://stats/devices - Estatísticas de e-mail por tipo de dispositivo (dados de 7 dias)
• sendgrid://stats/geography - Estatísticas de e-mail por localização geográfica (dados de 7 dias)
• sendgrid://stats/providers - Estatísticas de e-mail por provedor de caixa de correio (dados de 7 dias)

Prompts Disponíveis

• sendgrid_automation_help - Obtenha ajuda com automações de marketing
• sendgrid_campaign_help - Obtenha ajuda com campanhas de envio único
• sendgrid_contacts_help - Obtenha ajuda com gerenciamento abrangente de contatos
• sendgrid_list_management_help - Obtenha ajuda com operações CRUD de listas de e-mail
• sendgrid_update_list_help - Obtenha ajuda com atualização/renomeação de listas de e-mail
• sendgrid_contact_crud_help - Obtenha ajuda com operações de criar/ler/atualizar/excluir contatos
• sendgrid_custom_fields_help - Obtenha ajuda com gerenciamento de definições de campos personalizados
• sendgrid_segment_management_help - Obtenha ajuda com gerenciamento de segmentos de contatos dinâmicos
• sendgrid_sender_management_help - Obtenha ajuda com gerenciamento de identidade do remetente
• sendgrid_templates_help - Obtenha ajuda com criação e gerenciamento de modelos de e-mail dinâmicos
• sendgrid_suppressions_help - Obtenha ajuda com listas de supressão
• sendgrid_settings_help - Obtenha ajuda com configurações da conta
• sendgrid_mail_send_help - Obtenha ajuda com envio de e-mails
• sendgrid_stats_help - Obtenha ajuda com análise de desempenho e estatísticas de e-mail

Desenvolvimento e Contribuição

Esta seção é para desenvolvedores que desejam modificar o servidor ou contribuir com o desenvolvimento.

# Clone the repository
git clone https://github.com/deyikong/sendgrid-mcp.git
cd sendgrid-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Link for local development
npm link

# Test the local build
sendgrid-mcp

{
  "mcpServers": {
    "sendgrid": {
      "command": "node",
      "args": ["/absolute/path/to/sendgrid-mcp/build/index.js"],
      "env": {
        "SENDGRID_API_KEY": "SG.your_api_key_here",
        "READ_ONLY": "true"
      }
    }
  }
}

src/
├── index.ts                    # Main entry point
├── shared/                     # Shared utilities
│   ├── auth.ts                 # Authentication
│   ├── api.ts                  # SendGrid API client
│   ├── env.ts                  # Environment validation
│   └── types.ts                # Shared types
├── tools/                      # Tool definitions
│   ├── automations.ts          # Automation tools (7 tools)
│   ├── campaigns.ts            # Campaign tools (4 tools)
│   ├── contacts.ts             # Contact, list, segment & sender tools (25 tools)
│   ├── mail.ts                 # Mail sending tools (1 tool)
│   ├── misc.ts                 # Miscellaneous tools (1 tool)
│   ├── stats.ts                # Statistics tools (9 tools)
│   └── templates.ts            # Template tools (11 tools)
├── resources/                  # Resource definitions
│   └── sendgrid.ts             # MCP resources
└── prompts/                    # Prompt definitions
    └── help.ts                 # Help prompts

# Build the project
npm run build

# Test with environment variables
SENDGRID_API_KEY="SG.your_key" READ_ONLY="true" node build/index.js

Solução de Problemas

Problemas Comuns

Error: sendgrid-mcp: command not found

Error: SENDGRID_API_KEY must start with 'SG.'

Error: 403 Forbidden

❌ Operation blocked: Server is running in READ_ONLY mode

Error: Request timeout

Obtendo Ajuda

• Ajuda Integrada: Use os prompts de ajuda no seu cliente MCP (por exemplo, pergunte ao Claude: "ajuda com automações do sendgrid")
• API do SendGrid: Documentação Oficial da API
• Protocolo MCP: Documentação do Model Context Protocol
• Problemas: Reporte bugs no repositório do GitHub

Modo de Depuração

Habilite o registro detalhado definindo o LOG_LEVEL:

{
  "env": {
    "SENDGRID_API_KEY": "SG.your_key",
    "LOG_LEVEL": "debug"
  }
}

Isso fornecerá informações detalhadas sobre solicitações e respostas da API.

Segurança

Encontrou uma vulnerabilidade? Por favor, reporte-a de forma privada em vez de abrir um problema público — consulte SECURITY.md.

Operações Intencionalmente Não Suportadas

Um punhado de capacidades da API do SendGrid é deliberadamente deixado de fora deste servidor, além do que o modo READ_ONLY bloqueia em tempo de execução. Estas não são lacunas a serem preenchidas posteriormente — elas são excluídas porque permitir que um LLM as chame autonomamente carrega um raio de explosão em toda a conta que um alternador READ_ONLY sozinho não mitiga (um operador executando com READ_ONLY=false para escritas legítimas de automação de marketing não deveria estar a uma chamada de ferramenta com injeção de prompt de distância de perder acesso à conta ou orçamento de API):

• Criação/rotação/exclusão de chaves de API — apenas list_api_keys/get_api_key são expostos. Criar ou excluir chaves de API é um alvo clássico de injeção de prompt: uma página da web maliciosa ou e-mail que um agente processa poderia tentar enganá-lo para criar uma nova chave e exfiltrá-la.
• Convites de colegas de equipe, alterações de permissão e remoção — apenas list_teammates/get_teammate/list_pending_teammates são expostos. Adicionar, remover ou redefinir permissões de colegas de equipe é controle de acesso à conta com o mesmo risco de injeção que chaves de API.
• Compras de IP dedicado, controle de aquecimento e alterações na lista de permissões de acesso — apenas ferramentas de leitura/lista são expostas. IPs dedicados custam dinheiro real e afetam a infraestrutura de entregabilidade em toda a conta; erros na lista de permissões de acesso podem bloquear completamente o acesso legítimo à API.
• Gerenciamento de SSO e certificados — não exposto de forma alguma, em nenhuma forma. Configurar incorretamente o SSO pode bloquear uma organização inteira do login, e não há essencialmente nenhuma razão legítima para um assistente de chat gerenciar isso.

Se você precisar de qualquer um destes para uma automação específica, use o painel do SendGrid ou a API diretamente em vez de solicitar que este servidor os adicione — isso é um limite de design deliberado, não uma supervisão.

Licença

Este projeto é licenciado sob a Licença ISC.

Contribuição

1. Faça um fork do repositório
2. Crie um branch de funcionalidade
3. Faça suas alterações
4. Teste minuciosamente
5. Envie um pull request

Suporte

Para problemas relacionados a:

• API do SendGrid: Consulte a Documentação do SendGrid
• Protocolo MCP: Consulte o Model Context Protocol
• Este Servidor: Abra um problema neste repositório

Feedback

Trabalho no SendGrid e mantenho este projeto. Feedback, relatórios de bugs e solicitações de recursos são sempre bem-vindos — por favor, abra um problema ou inicie uma discussão no repositório.