Outlook MCP Server

Instructions

Implementation Reference

• src/outlook-manager.ts:479-568 (handler)

  Main handler function in OutlookManager class that finds the calendar event by ID/subject/date and sets its BusyStatus (Show As) via PowerShell script execution.

  async setShowAs(options: {
    eventId?: string;
    subject?: string;
    startDate?: Date;
    showAs: 'Free' | 'Tentative' | 'Busy' | 'OutOfOffice' | 'WorkingElsewhere';
  }): Promise<{ success: boolean; message: string }> {
    try {
      // Map ShowAs values to Outlook constants
      const showAsMap: Record<string, number> = {
        'Free': 0,           // olFree
        'Tentative': 1,      // olTentative
        'Busy': 2,           // olBusy
        'OutOfOffice': 3,    // olOutOfOffice
        'WorkingElsewhere': 4 // olWorkingElsewhere
      };
  
      const busyStatus = showAsMap[options.showAs];
      const eventId = options.eventId ? `"${options.eventId.replace(/"/g, '""')}"` : 'null';
      const subject = options.subject ? `"${options.subject.replace(/"/g, '""')}"` : 'null';
      const startDate = options.startDate ? `"${options.startDate.toISOString()}"` : 'null';
  
      const script = `
        try {
          Add-Type -AssemblyName "Microsoft.Office.Interop.Outlook" -ErrorAction Stop
          $outlook = New-Object -ComObject Outlook.Application -ErrorAction Stop
          $namespace = $outlook.GetNamespace("MAPI")
          $calendar = $namespace.GetDefaultFolder(9)
          
          $appointmentItem = $null
          
          # Find by ID if provided
          if (${eventId} -ne $null) {
            try {
              $appointmentItem = $namespace.GetItemFromID(${eventId})
            } catch { }
          }
          
          # Search by subject or date if not found
          if (-not $appointmentItem) {
            $items = $calendar.Items
            $items.Sort("[Start]")
            
            foreach ($item in $items) {
              $matchSubject = (${subject} -eq $null) -or ($item.Subject -like "*$(${subject})*")
              $matchDate = (${startDate} -eq $null) -or ([Math]::Abs(([DateTime]$item.Start - [DateTime]${startDate}).TotalMinutes) -lt 1)
              
              if ($matchSubject -and $matchDate) {
                $appointmentItem = $item
                break
              }
            }
          }
          
          if (-not $appointmentItem) {
            throw "Appointment not found. Please provide eventId, subject, or startDate."
          }
          
          $appointmentItem.BusyStatus = ${busyStatus}
          $appointmentItem.Save()
          
          Write-Output ([PSCustomObject]@{
            Success = $true
            Subject = $appointmentItem.Subject
            ShowAs = "${options.showAs}"
          } | ConvertTo-Json -Compress)
          
        } catch {
          Write-Output ([PSCustomObject]@{
            Success = $false
            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();
      const data = JSON.parse(cleanResult);
  
      if (!data.Success) {
        throw new Error(data.Error || 'Failed to set Show As');
      }
  
      return {
        success: true,
        message: `Show As set to ${options.showAs} for: ${data.Subject}`
      };
    } catch (error) {
      throw new Error(`Failed to set Show As: ${error instanceof Error ? error.message : String(error)}`);
    }
  }

• src/index.ts:685-701 (registration)

  Dispatcher case in CallToolRequest handler that extracts parameters and calls the setShowAs method on OutlookManager.

  case 'set_show_as': {
    const options = {
      eventId: (args as any)?.eventId,
      subject: (args as any)?.subject,
      startDate: (args as any)?.startDate ? new Date((args as any).startDate) : undefined,
      showAs: (args as any)?.showAs
    };
    const result = await outlookManager.setShowAs(options);
    return {
      content: [
        {
          type: 'text',
          text: `${result.success ? '✅' : '❌'} **Show As Updated**\n\n${result.message}`,
        },
      ],
    };
  }

• src/index.ts:245-270 (registration)

  Tool registration in ListToolsRequest handler, including name, description, and input schema definition.

    name: "set_show_as",
    description: "Set Show As (Free/Busy status) for a calendar event",
    inputSchema: {
      type: "object",
      properties: {
        eventId: {
          type: "string",
          description: "Event ID to update"
        },
        subject: {
          type: "string",
          description: "Subject of the event to find"
        },
        startDate: {
          type: "string",
          description: "Start date of the event to find (ISO 8601 format)"
        },
        showAs: {
          type: "string",
          enum: ["Free", "Tentative", "Busy", "OutOfOffice", "WorkingElsewhere"],
          description: "Show As status to set"
        }
      },
      required: ["showAs"]
    }
  },

• src/index.ts:247-269 (schema)

  Input schema definition for the set_show_as tool, specifying parameters and validation.

  inputSchema: {
    type: "object",
    properties: {
      eventId: {
        type: "string",
        description: "Event ID to update"
      },
      subject: {
        type: "string",
        description: "Subject of the event to find"
      },
      startDate: {
        type: "string",
        description: "Start date of the event to find (ISO 8601 format)"
      },
      showAs: {
        type: "string",
        enum: ["Free", "Tentative", "Busy", "OutOfOffice", "WorkingElsewhere"],
        description: "Show As status to set"
      }
    },
    required: ["showAs"]
  }