SendGrid MCP Server

Instructions

Implementation Reference

• src/tools/stats.ts:149-156 (handler)

  The async handler function that builds the SendGrid API request URL for category statistics and fetches the data using makeRequest.

  handler: async ({ categories, start_date, end_date, aggregated_by }: { categories: string; start_date: string; end_date?: string; aggregated_by?: string }): Promise<ToolResult> => {
    let url = `https://api.sendgrid.com/v3/categories/stats?categories=${encodeURIComponent(categories)}&start_date=${start_date}`;
    if (end_date) url += `&end_date=${end_date}`;
    if (aggregated_by) url += `&aggregated_by=${aggregated_by}`;
    
    const result = await makeRequest(url);
    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
  },

• src/tools/stats.ts:139-148 (schema)

  The tool configuration object containing title, description, and Zod-based inputSchema for parameter validation.

  config: {
    title: "Get Email Statistics by Category",
    description: "Retrieve email statistics for specific categories (available for previous 13 months only)",
    inputSchema: {
      categories: z.string().describe("Comma-separated list of categories to retrieve stats for"),
      start_date: z.string().describe("Start date in YYYY-MM-DD format"),
      end_date: z.string().optional().describe("End date in YYYY-MM-DD format (defaults to today)"),
      aggregated_by: z.enum(["day", "week", "month"]).optional().default("day").describe("How to group the statistics"),
    },
  },

• src/index.ts:20-23 (registration)

  Generic registration loop in the main MCP server file that registers all tools from allTools, including get_category_stats.

  // Register all tools
  for (const [name, tool] of Object.entries(allTools)) {
    server.registerTool(name, tool.config as any, tool.handler as any);
  }

• src/tools/index.ts:9-17 (registration)

  Aggregation of all tool sets into allTools, including statsTools which contains get_category_stats.

  export const allTools = {
    ...automationTools,
    ...campaignTools,
    ...contactTools,
    ...mailTools,
    ...miscTools,
    ...statsTools,
    ...templateTools,
  };