SendGrid MCP Server

Instructions

Implementation Reference

• src/services/sendgrid.ts:241-252 (handler)

  The core handler function within SendGridService that fetches email statistics from the SendGrid API using the /v3/stats endpoint.

  async getStats(params: {
    start_date: string;
    end_date?: string;
    aggregated_by?: 'day' | 'week' | 'month';
  }): Promise<SendGridStats> {
    const [response] = await this.client.request({
      method: 'GET',
      url: '/v3/stats',
      qs: params
    });
    return response.body as SendGridStats;
  }

• src/tools/index.ts:198-220 (registration)

  Tool definition registration including name, description, and input schema validation.

  {
    name: 'get_stats',
    description: 'Get SendGrid email statistics',
    inputSchema: {
      type: 'object',
      properties: {
        start_date: {
          type: 'string',
          description: 'Start date in YYYY-MM-DD format'
        },
        end_date: {
          type: 'string',
          description: 'End date in YYYY-MM-DD format (optional)'
        },
        aggregated_by: {
          type: 'string',
          enum: ['day', 'week', 'month'],
          description: 'How to aggregate the statistics (optional)'
        }
      },
      required: ['start_date']
    }
  },

• src/tools/index.ts:427-429 (handler)

  MCP tool call dispatcher that invokes the service handler and serializes the stats response as JSON text.

  case 'get_stats':
    const stats = await service.getStats(args);
    return { content: [{ type: 'text', text: JSON.stringify(stats, null, 2) }] };

• src/types/index.ts:35-57 (schema)

  TypeScript interface for the output type SendGridStats, defining the structure of the API response.

  export interface SendGridStats extends Array<{
    date: string;
    stats: Array<{
      metrics: {
        opens: number;
        clicks: number;
        bounces: number;
        spam_reports: number;
        unique_opens: number;
        unique_clicks: number;
        blocks: number;
        delivered: number;
        bounce_drops?: number;
        deferred?: number;
        invalid_emails?: number;
        processed?: number;
        requests?: number;
        spam_report_drops?: number;
        unsubscribe_drops?: number;
        unsubscribes?: number;
      };
    }>;
  }> {}