Fastmail MCP Server

Instructions

Implementation Reference

• src/contacts-calendar.ts:213-256 (handler)

  The main handler function in ContactsCalendarClient that creates a new calendar event using JMAP CalendarEvent/set API call. Performs permission checks, constructs the event object, sends the request, and returns the new event ID.
  async createCalendarEvent(event: { calendarId: string; title: string; description?: string; start: string; // ISO 8601 format end: string; // ISO 8601 format location?: string; participants?: Array<{ email: string; name?: string }>; }): Promise<string> { // 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 eventObject = { calendarId: event.calendarId, title: event.title, description: event.description || '', start: event.start, end: event.end, location: event.location || '', participants: event.participants || [] }; const request: JmapRequest = { using: ['urn:ietf:params:jmap:core', 'urn:ietf:params:jmap:calendars'], methodCalls: [ ['CalendarEvent/set', { accountId: session.accountId, create: { newEvent: eventObject } }, 'createEvent'] ] }; try { const response = await this.makeRequest(request); return response.methodResponses[0][1].created.newEvent.id; } catch (error) { throw new Error(`Calendar event creation not supported: ${error instanceof Error ? error.message : String(error)}. Try checking account permissions or enabling calendar API access in Fastmail settings.`); } }
• src/index.ts:329-373 (schema)

  MCP tool schema definition including inputSchema with properties, descriptions, and required fields for the create_calendar_event tool, registered in the ListTools response.
  { name: 'create_calendar_event', description: 'Create a new calendar event', inputSchema: { type: 'object', properties: { calendarId: { type: 'string', description: 'ID of the calendar to create the event in', }, title: { type: 'string', description: 'Event title', }, description: { type: 'string', description: 'Event description (optional)', }, start: { type: 'string', description: 'Start time in ISO 8601 format', }, end: { type: 'string', description: 'End time in ISO 8601 format', }, location: { type: 'string', description: 'Event location (optional)', }, participants: { type: 'array', items: { type: 'object', properties: { email: { type: 'string' }, name: { type: 'string' } } }, description: 'Event participants (optional)', }, }, required: ['calendarId', 'title', 'start', 'end'], }, },
• src/index.ts:866-889 (registration)

  Registration and dispatch handler in the MCP CallToolRequestSchema switch statement. Validates arguments, initializes the ContactsCalendarClient, calls the createCalendarEvent method, and formats the response.
  case 'create_calendar_event': { const { calendarId, title, description, start, end, location, participants } = args as any; if (!calendarId || !title || !start || !end) { throw new McpError(ErrorCode.InvalidParams, 'calendarId, title, start, and end are required'); } const contactsClient = initializeContactsCalendarClient(); const eventId = await contactsClient.createCalendarEvent({ calendarId, title, description, start, end, location, participants, }); return { content: [ { type: 'text', text: `Calendar event created successfully. Event ID: ${eventId}`, }, ], }; }