Outlook MCP Server

Instructions

Implementation Reference

• src/index.ts:310-331 (registration)

  Tool registration in the MCP server tools list, including name, description, and input schema definition.

  {
    name: "list_events",
    description: "List calendar events within a specified date range",
    inputSchema: {
      type: "object",
      properties: {
        startDate: {
          type: "string",
          description: "Start date (ISO 8601 format)"
        },
        endDate: {
          type: "string",
          description: "End date (ISO 8601 format, optional)"
        },
        calendar: {
          type: "string",
          description: "Calendar name (optional)"
        }
      },
      required: ["startDate"]
    }
  },

• src/index.ts:723-740 (handler)

  MCP server request handler that processes 'list_events' tool calls, invokes outlookManager.listEvents, and formats the response.

  case 'list_events': {
    const events = await outlookManager.listEvents({
      startDate: new Date((args as any)?.startDate),
      endDate: (args as any)?.endDate ? new Date((args as any)?.endDate) : undefined,
      calendar: (args as any)?.calendar
    });
    return {
      content: [
        {
          type: 'text',
          text: `📅 **Calendar Events**\nTotal: ${events.length} events\n\n` +
               events.map((event, index) => 
                 `${index + 1}. **${event.Subject}**\n   📍 ${event.Location || 'No location'}\n   🕐 ${event.Start} - ${event.End}\n   📋 ${event.Body ? event.Body.substring(0, 100) + '...' : 'No description'}\n   ID: ${event.Id}\n`
               ).join('\n')
        },
      ],
    };
  }

• src/outlook-manager.ts:655-736 (handler)

  Core handler function listEvents in OutlookManager that generates and executes PowerShell script to retrieve Outlook calendar events within a date range using COM interop.

  async listEvents(options: {
    startDate: Date;
    endDate?: Date;
    calendar?: string;
  }): Promise<any[]> {
    try {
      const endDate = options.endDate || options.startDate;
      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)
          `}
          
          # Create filter for date range
          $startDate = [DateTime]"${options.startDate.toISOString()}"
          $endDate = [DateTime]"${endDate.toISOString()}".AddDays(1)
          $filter = "[Start] >= '$($startDate.ToString('g'))' AND [End] <= '$($endDate.ToString('g'))'"
          
          # Get events
          $items = $calendar.Items.Restrict($filter)
          $items.Sort("[Start]")
          
          # Build JSON array
          $events = @()
          foreach ($item in $items) {
            $events += [PSCustomObject]@{
              Id = $item.EntryID
              Subject = $item.Subject
              Start = $item.Start.ToString("yyyy-MM-ddTHH:mm:ss")
              End = $item.End.ToString("yyyy-MM-ddTHH:mm:ss")
              Location = if ($item.Location) { $item.Location } else { "" }
              Body = if ($item.Body) { $item.Body } else { "" }
              BusyStatus = $item.BusyStatus
              IsAllDayEvent = $item.AllDayEvent
              Organizer = if ($item.Organizer) { $item.Organizer } else { "" }
              RequiredAttendees = if ($item.RequiredAttendees) { $item.RequiredAttendees } else { "" }
            }
          }
          
          Write-Output ($events | 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 === '') {
        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 list events: ${error instanceof Error ? error.message : String(error)}`);
    }
  }