Fastmail MCP Server

Instructions

Implementation Reference

• src/index.ts:146-163 (schema)

  Tool schema definition including name, description, and input schema for list_emails

  {
    name: 'list_emails',
    description: 'List emails from a mailbox',
    inputSchema: {
      type: 'object',
      properties: {
        mailboxId: {
          type: 'string',
          description: 'ID of the mailbox to list emails from (optional, defaults to all)',
        },
        limit: {
          type: 'number',
          description: 'Maximum number of emails to return (default: 20)',
          default: 20,
        },
      },
    },
  },

• src/index.ts:674-685 (handler)

  MCP tool handler for 'list_emails' that extracts parameters and calls JmapClient.getEmails

  case 'list_emails': {
    const { mailboxId, limit = 20 } = args as any;
    const emails = await client.getEmails(mailboxId, limit);
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(emails, null, 2),
        },
      ],
    };
  }

• src/jmap-client.ts:96-120 (handler)

  Core implementation of email listing using JMAP protocol: queries emails optionally filtered by mailbox, sorted by receivedAt descending, fetches specified properties.

  async getEmails(mailboxId?: string, limit: number = 20): Promise<any[]> {
    const session = await this.getSession();
    
    const filter = mailboxId ? { inMailbox: mailboxId } : {};
    
    const request: JmapRequest = {
      using: ['urn:ietf:params:jmap:core', 'urn:ietf:params:jmap:mail'],
      methodCalls: [
        ['Email/query', {
          accountId: session.accountId,
          filter,
          sort: [{ property: 'receivedAt', isAscending: false }],
          limit
        }, 'query'],
        ['Email/get', {
          accountId: session.accountId,
          '#ids': { resultOf: 'query', name: 'Email/query', path: '/ids' },
          properties: ['id', 'subject', 'from', 'to', 'receivedAt', 'preview', 'hasAttachment']
        }, 'emails']
      ]
    };
  
    const response = await this.makeRequest(request);
    return response.methodResponses[1][1].list;
  }