Outlook MCP Server

Instructions

Implementation Reference

• src/outlook-manager.ts:875-990 (handler)

  The primary handler function for the 'find_free_slots' tool. It constructs a PowerShell script to interact with Outlook via COM, retrieves busy events in the specified date range, calculates free slots of the desired duration during work hours (default 9-17), skips weekends, and returns an array of available {Start, End} slots.

  async findFreeSlots(options: {
    startDate: Date;
    endDate?: Date;
    duration?: number;
    workDayStart?: number;
    workDayEnd?: number;
    calendar?: string;
  }): Promise<any[]> {
    try {
      const endDate = options.endDate || new Date(options.startDate.getTime() + 7 * 24 * 60 * 60 * 1000);
      const duration = options.duration || 30;
      const workDayStart = options.workDayStart || 9;
      const workDayEnd = options.workDayEnd || 17;
      const calendarName = options.calendar || '';
      
      const script = `
        try {
          Add-Type -AssemblyName "Microsoft.Office.Interop.Outlook" -ErrorAction Stop
          $outlook = New-Object -ComObject Outlook.Application -ErrorAction Stop
          $namespace = $outlook.GetNamespace("MAPI")
          
          # Get calendar
          ${calendarName ? `
          $calendar = $null
          foreach ($folder in $namespace.Folders) {
            if ($folder.Name -eq "${calendarName.replace(/"/g, '""')}") {
              $calendar = $folder.Folders("Calendar")
              break
            }
          }
          if (-not $calendar) { throw "Calendar not found: ${calendarName.replace(/"/g, '""')}" }
          ` : `
          $calendar = $namespace.GetDefaultFolder(9)
          `}
          
          # Get all events in date range
          $startDate = [DateTime]"${options.startDate.toISOString()}"
          $endDate = [DateTime]"${endDate.toISOString()}"
          $filter = "[Start] >= '$($startDate.ToString('g'))' AND [End] <= '$($endDate.AddDays(1).ToString('g'))'"
          $items = $calendar.Items.Restrict($filter)
          
          # Build busy slots array
          $busySlots = @()
          foreach ($item in $items) {
            if ($item.BusyStatus -eq 2 -or $item.BusyStatus -eq 3) { # Busy or OutOfOffice
              $busySlots += [PSCustomObject]@{
                Start = $item.Start
                End = $item.End
              }
            }
          }
          
          # Find free slots
          $freeSlots = @()
          $currentDate = $startDate.Date
          
          while ($currentDate -le $endDate.Date) {
            # Skip weekends
            $dayOfWeek = $currentDate.DayOfWeek
            if ($dayOfWeek -ne [DayOfWeek]::Saturday -and $dayOfWeek -ne [DayOfWeek]::Sunday) {
              $slotStart = $currentDate.AddHours(${workDayStart})
              $workDayEndTime = $currentDate.AddHours(${workDayEnd})
              
              while ($slotStart.AddMinutes(${duration}) -le $workDayEndTime) {
                $slotEnd = $slotStart.AddMinutes(${duration})
                
                # Check if slot is free
                $isFree = $true
                foreach ($busy in $busySlots) {
                  if ($slotStart -lt $busy.End -and $slotEnd -gt $busy.Start) {
                    $isFree = $false
                    break
                  }
                }
                
                if ($isFree) {
                  $freeSlots += [PSCustomObject]@{
                    Start = $slotStart.ToString("yyyy-MM-ddTHH:mm:ss")
                    End = $slotEnd.ToString("yyyy-MM-ddTHH:mm:ss")
                  }
                }
                
                $slotStart = $slotStart.AddMinutes(30)
              }
            }
            
            $currentDate = $currentDate.AddDays(1)
          }
          
          Write-Output ($freeSlots | ConvertTo-Json -Compress)
          
        } catch {
          Write-Output ([PSCustomObject]@{
            Error = $_.Exception.Message
          } | ConvertTo-Json -Compress)
        }
      `;
  
      const result = await this.executePowerShell(script);
      const cleanResult = result.replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g, '').trim();
      
      if (!cleanResult || cleanResult === '' || cleanResult === '[]') {
        return [];
      }
      
      const data = JSON.parse(cleanResult);
      
      if (data.Error) {
        throw new Error(data.Error);
      }
      
      return Array.isArray(data) ? data : [data];
    } catch (error) {
      throw new Error(`Failed to find free slots: ${error instanceof Error ? error.message : String(error)}`);
    }
  }

• src/index.ts:397-428 (schema)

  The input schema and description for the 'find_free_slots' tool, defining parameters and validation as part of the MCP tools list.

  name: "find_free_slots",
  description: "Find available time slots in the calendar",
  inputSchema: {
    type: "object",
    properties: {
      startDate: {
        type: "string",
        description: "Start date (ISO 8601 format)"
      },
      endDate: {
        type: "string",
        description: "End date (ISO 8601 format, optional, defaults to 7 days from start)"
      },
      duration: {
        type: "number",
        description: "Duration in minutes (optional, defaults to 30)"
      },
      workDayStart: {
        type: "number",
        description: "Work day start hour (0-23) (optional, defaults to 9)"
      },
      workDayEnd: {
        type: "number",
        description: "Work day end hour (0-23) (optional, defaults to 17)"
      },
      calendar: {
        type: "string",
        description: "Calendar name (optional)"
      }
    },
    required: ["startDate"]
  }

• src/index.ts:779-800 (registration)

  MCP server request handler case that dispatches 'find_free_slots' tool calls to the outlookManager implementation and formats the response.

  case 'find_free_slots': {
    const freeSlots = await outlookManager.findFreeSlots({
      startDate: new Date((args as any)?.startDate),
      endDate: (args as any)?.endDate ? new Date((args as any)?.endDate) : undefined,
      duration: (args as any)?.duration,
      workDayStart: (args as any)?.workDayStart,
      workDayEnd: (args as any)?.workDayEnd,
      calendar: (args as any)?.calendar
    });
    return {
      content: [
        {
          type: 'text',
          text: `🆓 **Free Time Slots**\nTotal: ${freeSlots.length} slots found\n\n` +
               freeSlots.slice(0, 20).map((slot, index) => 
                 `${index + 1}. ${slot.Start} - ${slot.End}`
               ).join('\n') +
               (freeSlots.length > 20 ? `\n\n... and ${freeSlots.length - 20} more slots` : '')
        },
      ],
    };
  }