list_calendar_events

Retrieve calendar events from Fastmail to view schedules, check availability, or manage appointments using calendar IDs and customizable limits.

Instructions

List events from a calendar

Input Schema

TableJSON Schema

Name	Required	Description	Default
`calendarId`	No	ID of the calendar (optional, defaults to all calendars)
`limit`	No	Maximum number of events to return (default: 50)

Implementation Reference

src/index.ts:835-847 (handler)

MCP tool handler that initializes the ContactsCalendarClient and calls getCalendarEvents to list events from a specific calendar.

case 'list_calendar_events': {
  const { calendarId, limit = 50 } = args as any;
  const contactsClient = initializeContactsCalendarClient();
  const events = await contactsClient.getCalendarEvents(calendarId, limit);
  return {
    content: [
      {
        type: 'text',
        text: JSON.stringify(events, null, 2),
      },
    ],
  };
}

src/contacts-calendar.ts:150-184 (helper)

Core implementation of listing calendar events using JMAP CalendarEvent/query and CalendarEvent/get methods, with permission checks and filtering by calendarId.

async getCalendarEvents(calendarId?: string, limit: number = 50): 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 filter = calendarId ? { inCalendar: calendarId } : {};
  
  const request: JmapRequest = {
    using: ['urn:ietf:params:jmap:core', 'urn:ietf:params:jmap:calendars'],
    methodCalls: [
      ['CalendarEvent/query', {
        accountId: session.accountId,
        filter,
        sort: [{ property: 'start', isAscending: true }],
        limit
      }, 'query'],
      ['CalendarEvent/get', {
        accountId: session.accountId,
        '#ids': { resultOf: 'query', name: 'CalendarEvent/query', path: '/ids' },
        properties: ['id', 'title', 'description', 'start', 'end', 'location', 'participants']
      }, 'events']
    ]
  };

  try {
    const response = await this.makeRequest(request);
    return response.methodResponses[1][1].list;
  } catch (error) {
    throw new Error(`Calendar events access not supported: ${error instanceof Error ? error.message : String(error)}. Try checking account permissions or enabling calendar API access in Fastmail settings.`);
  }
}

src/index.ts:297-314 (schema)

Input schema definition for the list_calendar_events tool, specifying optional calendarId and limit parameters.

{
  name: 'list_calendar_events',
  description: 'List events from a calendar',
  inputSchema: {
    type: 'object',
    properties: {
      calendarId: {
        type: 'string',
        description: 'ID of the calendar (optional, defaults to all calendars)',
      },
      limit: {
        type: 'number',
        description: 'Maximum number of events to return (default: 50)',
        default: 50,
      },
    },
  },
},

src/index.ts:1167-1170 (registration)

Lists list_calendar_events as one of the available calendar functions in the check_function_availability tool.

functions: ['list_calendars', 'list_calendar_events', 'get_calendar_event', 'create_calendar_event'],
note: session.capabilities['urn:ietf:params:jmap:calendars'] ? 
  'Calendar is available' : 
  'Calendar access not available - may require enabling in Fastmail account settings',

Fastmail MCP Server