Google Workspace MCP Server

Instructions

Implementation Reference

• src/index.ts:299-371 (handler)

  The primary handler function for executing the 'list_emails' tool. It retrieves recent emails from the Gmail inbox, extracts headers and body content, and formats the response as JSON.

  private async handleListEmails(args: any) {
    try {
      const maxResults = args?.maxResults || 10;
      const query = args?.query || "";
      const getEmailBody = (payload: any): string => {
        if (!payload) return "";
  
        if (payload.body && payload.body.data) {
          return Buffer.from(payload.body.data, "base64").toString("utf-8");
        }
  
        if (payload.parts && payload.parts.length > 0) {
          for (const part of payload.parts) {
            if (part.mimeType === "text/plain") {
              return Buffer.from(part.body.data, "base64").toString("utf-8");
            }
          }
        }
  
        return "(No body content)";
      };
  
      const response = await this.gmail.users.messages.list({
        userId: "me",
        maxResults,
        q: query,
      });
  
      const messages = response.data.messages || [];
      const emailDetails = await Promise.all(
        messages.map(async (msg) => {
          const detail = await this.gmail.users.messages.get({
            userId: "me",
            id: msg.id!,
          });
  
          const headers = detail.data.payload?.headers;
          const subject =
            headers?.find((h) => h.name === "Subject")?.value || "";
          const from = headers?.find((h) => h.name === "From")?.value || "";
          const date = headers?.find((h) => h.name === "Date")?.value || "";
          const body = getEmailBody(detail.data.payload);
  
          return {
            id: msg.id,
            subject,
            from,
            date,
            body,
          };
        })
      );
  
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(emailDetails, null, 2),
          },
        ],
      };
    } catch (error: any) {
      return {
        content: [
          {
            type: "text",
            text: `Error fetching emails: ${error.message}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/index.ts:66-78 (schema)

  Input schema definition for the 'list_emails' tool, specifying optional parameters for maxResults and query.

  inputSchema: {
    type: "object",
    properties: {
      maxResults: {
        type: "number",
        description: "Maximum number of emails to return (default: 10)",
      },
      query: {
        type: "string",
        description: "Search query to filter emails",
      },
    },
  },

• src/index.ts:63-79 (registration)

  Registration of the 'list_emails' tool in the ListToolsRequestSchema handler, including name, description, and input schema.

  {
    name: "list_emails",
    description: "List recent emails from Gmail inbox",
    inputSchema: {
      type: "object",
      properties: {
        maxResults: {
          type: "number",
          description: "Maximum number of emails to return (default: 10)",
        },
        query: {
          type: "string",
          description: "Search query to filter emails",
        },
      },
    },
  },

• src/index.ts:274-275 (registration)

  Dispatch case in the CallToolRequestSchema switch statement that routes calls to the 'list_emails' handler.

  case "list_emails":
    return await this.handleListEmails(request.params.arguments);

• src/index.ts:303-319 (helper)

  Inner helper function used by handleListEmails to extract plain text body from Gmail message payloads, handling both simple and multipart messages.

  const getEmailBody = (payload: any): string => {
    if (!payload) return "";
  
    if (payload.body && payload.body.data) {
      return Buffer.from(payload.body.data, "base64").toString("utf-8");
    }
  
    if (payload.parts && payload.parts.length > 0) {
      for (const part of payload.parts) {
        if (part.mimeType === "text/plain") {
          return Buffer.from(part.body.data, "base64").toString("utf-8");
        }
      }
    }
  
    return "(No body content)";
  };