Fastmail MCP Server

Instructions

Implementation Reference

• src/index.ts:687-701 (handler)

  MCP CallToolRequestSchema handler case for 'get_email': validates emailId parameter and delegates to JmapClient.getEmailById, returning JSON stringified email content.

  case 'get_email': {
    const { emailId } = args as any;
    if (!emailId) {
      throw new McpError(ErrorCode.InvalidParams, 'emailId is required');
    }
    const email = await client.getEmailById(emailId);
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(email, null, 2),
        },
      ],
    };
  }

• src/index.ts:164-177 (schema)

  Input schema definition for the 'get_email' tool in ListToolsRequestSchema response, specifying required 'emailId' string parameter.

  {
    name: 'get_email',
    description: 'Get a specific email by ID',
    inputSchema: {
      type: 'object',
      properties: {
        emailId: {
          type: 'string',
          description: 'ID of the email to retrieve',
        },
      },
      required: ['emailId'],
    },
  },

• src/jmap-client.ts:122-152 (helper)

  JmapClient helper method getEmailById that performs JMAP Email/get request to fetch full email details including body and attachments by email ID.

  async getEmailById(id: string): Promise<any> {
    const session = await this.getSession();
    
    const request: JmapRequest = {
      using: ['urn:ietf:params:jmap:core', 'urn:ietf:params:jmap:mail'],
      methodCalls: [
        ['Email/get', {
          accountId: session.accountId,
          ids: [id],
          properties: ['id', 'subject', 'from', 'to', 'cc', 'bcc', 'receivedAt', 'textBody', 'htmlBody', 'attachments', 'bodyValues'],
          bodyProperties: ['partId', 'blobId', 'type', 'size'],
          fetchTextBodyValues: true,
          fetchHTMLBodyValues: true,
        }, 'email']
      ]
    };
  
    const response = await this.makeRequest(request);
    const result = response.methodResponses[0][1];
    
    if (result.notFound && result.notFound.includes(id)) {
      throw new Error(`Email with ID '${id}' not found`);
    }
    
    const email = result.list[0];
    if (!email) {
      throw new Error(`Email with ID '${id}' not found or not accessible`);
    }
    
    return email;
  }