Fastmail MCP Server

Instructions

Implementation Reference

• src/index.ts:289-296 (registration)

  Tool registration including name, description, and input schema (empty object since no parameters required) in the MCP tools list.

  {
    name: 'list_calendars',
    description: 'List all calendars',
    inputSchema: {
      type: 'object',
      properties: {},
    },
  },

• src/index.ts:822-833 (handler)

  MCP server switch-case handler that initializes the contacts/calendar client and delegates to getCalendars() method, returning JSON response.

  case 'list_calendars': {
    const contactsClient = initializeContactsCalendarClient();
    const calendars = await contactsClient.getCalendars();
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(calendars, null, 2),
        },
      ],
    };
  }

• src/contacts-calendar.ts:123-148 (handler)

  Core implementation of list_calendars: checks JMAP calendars capability/permission, constructs and sends Calendar/get JMAP request, returns list of calendars.

  async getCalendars(): Promise<any[]> {
    // Check permissions first
    const hasPermission = await this.checkCalendarsPermission();
    if (!hasPermission) {
      throw new Error('Calendar access not available. This account may not have JMAP calendar permissions enabled. Please check your Fastmail account settings or contact support to enable calendar API access.');
    }
  
    const session = await this.getSession();
    
    const request: JmapRequest = {
      using: ['urn:ietf:params:jmap:core', 'urn:ietf:params:jmap:calendars'],
      methodCalls: [
        ['Calendar/get', {
          accountId: session.accountId
        }, 'calendars']
      ]
    };
  
    try {
      const response = await this.makeRequest(request);
      return response.methodResponses[0][1].list;
    } catch (error) {
      // Calendar access might require special permissions
      throw new Error(`Calendar access not supported or requires additional permissions. This may be due to account settings or JMAP scope limitations: ${error instanceof Error ? error.message : String(error)}. Try checking account permissions or enabling calendar API access in Fastmail settings.`);
    }
  }

• src/contacts-calendar.ts:10-13 (helper)

  Helper method used by getCalendars() to verify if the JMAP calendars capability is enabled for the account.

  private async checkCalendarsPermission(): Promise<boolean> {
    const session = await this.getSession();
    return !!session.capabilities['urn:ietf:params:jmap:calendars'];
  }