Fastmail MCP Server

Instructions

Implementation Reference

• src/index.ts:548-560 (registration)

  Tool registration in ListTools response, including name, description, and input schema definition.

  {
    name: 'get_mailbox_stats',
    description: 'Get statistics for a mailbox (unread count, total emails, etc.)',
    inputSchema: {
      type: 'object',
      properties: {
        mailboxId: {
          type: 'string',
          description: 'ID of the mailbox (optional, defaults to all mailboxes)',
        },
      },
    },
  },

• src/index.ts:1050-1062 (handler)

  MCP server dispatch handler for get_mailbox_stats tool that parses arguments and delegates to JmapClient.getMailboxStats.

  case 'get_mailbox_stats': {
    const { mailboxId } = args as any;
    const client = initializeClient();
    const stats = await client.getMailboxStats(mailboxId);
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(stats, null, 2),
        },
      ],
    };
  }

• src/jmap-client.ts:609-640 (handler)

  Core implementation in JmapClient that fetches mailbox statistics via JMAP Mailbox/get API call, handling both specific mailbox and all mailboxes cases.

  async getMailboxStats(mailboxId?: string): Promise<any> {
    const session = await this.getSession();
    
    if (mailboxId) {
      // Get stats for specific mailbox
      const request: JmapRequest = {
        using: ['urn:ietf:params:jmap:core', 'urn:ietf:params:jmap:mail'],
        methodCalls: [
          ['Mailbox/get', {
            accountId: session.accountId,
            ids: [mailboxId],
            properties: ['id', 'name', 'role', 'totalEmails', 'unreadEmails', 'totalThreads', 'unreadThreads']
          }, 'mailbox']
        ]
      };
  
      const response = await this.makeRequest(request);
      return response.methodResponses[0][1].list[0];
    } else {
      // Get stats for all mailboxes
      const mailboxes = await this.getMailboxes();
      return mailboxes.map(mb => ({
        id: mb.id,
        name: mb.name,
        role: mb.role,
        totalEmails: mb.totalEmails || 0,
        unreadEmails: mb.unreadEmails || 0,
        totalThreads: mb.totalThreads || 0,
        unreadThreads: mb.unreadThreads || 0
      }));
    }
  }