Fastmail MCP Server

Instructions

Implementation Reference

• src/index.ts:1194-1286 (handler)

  Main handler for the 'test_bulk_operations' tool. Fetches recent emails from inbox, simulates or executes bulk mark read/unread operations (with dryRun option), and returns detailed results including test emails and operation outcomes.
  case 'test_bulk_operations': { const { dryRun = true, limit = 3 } = args as any; const client = initializeClient(); // Get some recent emails to test with const testLimit = Math.min(Math.max(limit, 1), 10); const emails = await client.getRecentEmails(testLimit, 'inbox'); if (emails.length === 0) { return { content: [ { type: 'text', text: 'No emails found for bulk operation testing. Try sending yourself a test email first.', }, ], }; } const emailIds = emails.slice(0, testLimit).map(email => email.id); const operations = [ { name: 'bulk_mark_read', description: `Mark ${emailIds.length} emails as read`, parameters: { emailIds, read: true } }, { name: 'bulk_mark_read (undo)', description: `Mark ${emailIds.length} emails as unread (undo previous)`, parameters: { emailIds, read: false } } ]; const results = { testEmails: emails.map(email => ({ id: email.id, subject: email.subject, from: email.from?.[0]?.email || 'unknown', receivedAt: email.receivedAt })), operations: [] as any[] }; if (dryRun) { results.operations = operations.map(op => ({ ...op, status: 'DRY RUN - Would execute but not actually performed', executed: false })); return { content: [ { type: 'text', text: `BULK OPERATIONS TEST (DRY RUN)\n\n${JSON.stringify(results, null, 2)}\n\nTo actually execute the test, set dryRun: false`, }, ], }; } else { // Execute the test operations for (const operation of operations) { try { await client.bulkMarkRead(operation.parameters.emailIds, operation.parameters.read); results.operations.push({ ...operation, status: 'SUCCESS', executed: true, timestamp: new Date().toISOString() }); // Small delay between operations await new Promise(resolve => setTimeout(resolve, 500)); } catch (error) { results.operations.push({ ...operation, status: 'FAILED', executed: false, error: error instanceof Error ? error.message : String(error), timestamp: new Date().toISOString() }); } } return { content: [ { type: 'text', text: `BULK OPERATIONS TEST (EXECUTED)\n\n${JSON.stringify(results, null, 2)}`, }, ], }; } }
• src/index.ts:631-649 (schema)

  Input schema and registration details for the 'test_bulk_operations' tool, defining parameters dryRun and limit.
  { name: 'test_bulk_operations', description: 'Test bulk operations by finding recent emails and performing safe operations (mark read/unread)', inputSchema: { type: 'object', properties: { dryRun: { type: 'boolean', description: 'If true, only shows what would be done without making changes (default: true)', default: true, }, limit: { type: 'number', description: 'Number of emails to test with (default: 3, max: 10)', default: 3, }, }, }, },
• src/index.ts:135-652 (registration)

  Registration of the tool in the ListToolsRequestSchema handler, including it in the list of available tools.
  server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ { name: 'list_mailboxes', description: 'List all mailboxes in the Fastmail account', inputSchema: { type: 'object', properties: {}, }, }, { 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, }, }, }, }, { name: 'get_email', description: 'Get a specific email by ID', inputSchema: { type: 'object', properties: { emailId: { type: 'string', description: 'ID of the email to retrieve', }, }, required: ['emailId'], }, }, { name: 'send_email', description: 'Send an email', inputSchema: { type: 'object', properties: { to: { type: 'array', items: { type: 'string' }, description: 'Recipient email addresses', }, cc: { type: 'array', items: { type: 'string' }, description: 'CC email addresses (optional)', }, bcc: { type: 'array', items: { type: 'string' }, description: 'BCC email addresses (optional)', }, from: { type: 'string', description: 'Sender email address (optional, defaults to account primary email)', }, mailboxId: { type: 'string', description: 'Mailbox ID to save the email to (optional, defaults to Drafts folder)', }, subject: { type: 'string', description: 'Email subject', }, textBody: { type: 'string', description: 'Plain text body (optional)', }, htmlBody: { type: 'string', description: 'HTML body (optional)', }, }, required: ['to', 'subject'], }, }, { name: 'search_emails', description: 'Search emails by subject or content', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Search query string', }, limit: { type: 'number', description: 'Maximum number of results (default: 20)', default: 20, }, }, required: ['query'], }, }, { name: 'list_contacts', description: 'List contacts from the address book', inputSchema: { type: 'object', properties: { limit: { type: 'number', description: 'Maximum number of contacts to return (default: 50)', default: 50, }, }, }, }, { name: 'get_contact', description: 'Get a specific contact by ID', inputSchema: { type: 'object', properties: { contactId: { type: 'string', description: 'ID of the contact to retrieve', }, }, required: ['contactId'], }, }, { name: 'search_contacts', description: 'Search contacts by name or email', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Search query string', }, limit: { type: 'number', description: 'Maximum number of results (default: 20)', default: 20, }, }, required: ['query'], }, }, { name: 'list_calendars', description: 'List all calendars', inputSchema: { type: 'object', properties: {}, }, }, { 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, }, }, }, }, { name: 'get_calendar_event', description: 'Get a specific calendar event by ID', inputSchema: { type: 'object', properties: { eventId: { type: 'string', description: 'ID of the event to retrieve', }, }, required: ['eventId'], }, }, { 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'], }, }, { name: 'list_identities', description: 'List sending identities (email addresses that can be used for sending)', inputSchema: { type: 'object', properties: {}, }, }, { name: 'get_recent_emails', description: 'Get the most recent emails from inbox (like top-ten)', inputSchema: { type: 'object', properties: { limit: { type: 'number', description: 'Number of recent emails to retrieve (default: 10, max: 50)', default: 10, }, mailboxName: { type: 'string', description: 'Mailbox to search (default: inbox)', default: 'inbox', }, }, }, }, { name: 'mark_email_read', description: 'Mark an email as read or unread', inputSchema: { type: 'object', properties: { emailId: { type: 'string', description: 'ID of the email to mark', }, read: { type: 'boolean', description: 'true to mark as read, false to mark as unread', default: true, }, }, required: ['emailId'], }, }, { name: 'delete_email', description: 'Delete an email (move to trash)', inputSchema: { type: 'object', properties: { emailId: { type: 'string', description: 'ID of the email to delete', }, }, required: ['emailId'], }, }, { name: 'move_email', description: 'Move an email to a different mailbox', inputSchema: { type: 'object', properties: { emailId: { type: 'string', description: 'ID of the email to move', }, targetMailboxId: { type: 'string', description: 'ID of the target mailbox', }, }, required: ['emailId', 'targetMailboxId'], }, }, { name: 'get_email_attachments', description: 'Get list of attachments for an email', inputSchema: { type: 'object', properties: { emailId: { type: 'string', description: 'ID of the email', }, }, required: ['emailId'], }, }, { name: 'download_attachment', description: 'Download an email attachment', inputSchema: { type: 'object', properties: { emailId: { type: 'string', description: 'ID of the email', }, attachmentId: { type: 'string', description: 'ID of the attachment', }, }, required: ['emailId', 'attachmentId'], }, }, { name: 'advanced_search', description: 'Advanced email search with multiple criteria', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Text to search for in subject/body', }, from: { type: 'string', description: 'Filter by sender email', }, to: { type: 'string', description: 'Filter by recipient email', }, subject: { type: 'string', description: 'Filter by subject', }, hasAttachment: { type: 'boolean', description: 'Filter emails with attachments', }, isUnread: { type: 'boolean', description: 'Filter unread emails', }, mailboxId: { type: 'string', description: 'Search within specific mailbox', }, after: { type: 'string', description: 'Emails after this date (ISO 8601)', }, before: { type: 'string', description: 'Emails before this date (ISO 8601)', }, limit: { type: 'number', description: 'Maximum results (default: 50)', default: 50, }, }, }, }, { name: 'get_thread', description: 'Get all emails in a conversation thread', inputSchema: { type: 'object', properties: { threadId: { type: 'string', description: 'ID of the thread/conversation', }, }, required: ['threadId'], }, }, { 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)', }, }, }, }, { name: 'get_account_summary', description: 'Get overall account summary with statistics', inputSchema: { type: 'object', properties: {}, }, }, { name: 'bulk_mark_read', description: 'Mark multiple emails as read/unread', inputSchema: { type: 'object', properties: { emailIds: { type: 'array', items: { type: 'string' }, description: 'Array of email IDs to mark', }, read: { type: 'boolean', description: 'true to mark as read, false as unread', default: true, }, }, required: ['emailIds'], }, }, { name: 'bulk_move', description: 'Move multiple emails to a mailbox', inputSchema: { type: 'object', properties: { emailIds: { type: 'array', items: { type: 'string' }, description: 'Array of email IDs to move', }, targetMailboxId: { type: 'string', description: 'ID of target mailbox', }, }, required: ['emailIds', 'targetMailboxId'], }, }, { name: 'bulk_delete', description: 'Delete multiple emails (move to trash)', inputSchema: { type: 'object', properties: { emailIds: { type: 'array', items: { type: 'string' }, description: 'Array of email IDs to delete', }, }, required: ['emailIds'], }, }, { name: 'check_function_availability', description: 'Check which MCP functions are available based on account permissions', inputSchema: { type: 'object', properties: {}, }, }, { name: 'test_bulk_operations', description: 'Test bulk operations by finding recent emails and performing safe operations (mark read/unread)', inputSchema: { type: 'object', properties: { dryRun: { type: 'boolean', description: 'If true, only shows what would be done without making changes (default: true)', default: true, }, limit: { type: 'number', description: 'Number of emails to test with (default: 3, max: 10)', default: 3, }, }, }, }, ], }; });