Outlook MCP Server

Instructions

Implementation Reference

• src/index.ts:30-42 (schema)

  Input/output schema definition for the get_inbox_emails tool, specifying optional count parameter.

    name: "get_inbox_emails",
    description: "Get inbox email list",
    inputSchema: {
      type: "object",
      properties: {
        count: {
          type: "number",
          description: "Number of emails to retrieve",
          default: 10
        }
      }
    }
  },

• src/index.ts:466-480 (handler)

  MCP CallToolRequestSchema handler case that executes get_inbox_emails by calling outlookManager.getInboxEmails and formatting the markdown response.

  case 'get_inbox_emails': {
    const count = (args as any)?.count || 10;
    const emails = await outlookManager.getInboxEmails(count);
    return {
      content: [
        {
          type: 'text',
          text: `📊 **Email Overview**\nTotal: ${emails.length} emails\nUnread: ${emails.filter(e => !e.isRead).length} emails\n\n📋 **Email List:**\n` + 
               emails.map((email, index) => 
                 `${index + 1}. ${email.isRead ? '✅' : '📩'} **${email.subject}**\n   From: ${email.sender}\n   Time: ${email.receivedTime}\n   Preview: ${email.body?.substring(0, 100)}...\n`
               ).join('\n')
        },
      ],
    };
  }

• src/outlook-manager.ts:216-218 (handler)

  Specific handler method for fetching inbox emails by calling the generic getEmailsFromFolder with Inbox folder ID (6).

  async getInboxEmails(count: number = 10): Promise<EmailMessage[]> {
    return this.getEmailsFromFolder(6, count, "[ReceivedTime]"); // 6 = Inbox
  }

• src/outlook-manager.ts:87-191 (helper)

  Core helper function that runs PowerShell script via child_process.spawn to interact with Outlook COM API, retrieve emails from specified folder, parse JSON output, and map to EmailMessage[] objects.

  private async getEmailsFromFolder(folderType: number, count: number = 10, sortBy: string = "[ReceivedTime]"): Promise<EmailMessage[]> {
    const script = `
      try {
        Add-Type -AssemblyName "Microsoft.Office.Interop.Outlook" -ErrorAction Stop
        $outlook = New-Object -ComObject Outlook.Application -ErrorAction Stop
        $namespace = $outlook.GetNamespace("MAPI")
        $folder = $namespace.GetDefaultFolder(${folderType})
        
        if ($folder.Items.Count -eq 0) {
          Write-Output "[]"
          exit 0
        }
        
        $items = $folder.Items
        $items.Sort("${sortBy}", $true)
        
        $emails = @()
        $counter = 0
        
        foreach ($item in $items) {
          if ($counter -ge ${count}) { break }
          
          try {
            $subject = if ($item.Subject) { $item.Subject.ToString() -replace '[\\x00-\\x1F\\x7F]', '' } else { "No Subject" }
            $sender = if ($item.SenderEmailAddress) { $item.SenderEmailAddress.ToString() -replace '[\\x00-\\x1F\\x7F]', '' } else { "Unknown" }
            $body = if ($item.Body) { 
              $bodyStr = $item.Body.ToString() -replace '[\\x00-\\x1F\\x7F]', ''
              if ($bodyStr.Length -gt 150) { $bodyStr.Substring(0, 150) + "..." } else { $bodyStr }
            } else { "" }
            
            $timeStamp = if ($item.SentOn -and ${folderType} -eq 5) { 
              $item.SentOn.ToString("yyyy-MM-dd HH:mm:ss") 
            } elseif ($item.ReceivedTime) { 
              $item.ReceivedTime.ToString("yyyy-MM-dd HH:mm:ss") 
            } else { 
              (Get-Date).ToString("yyyy-MM-dd HH:mm:ss") 
            }
            
            $emails += [PSCustomObject]@{
              Id = if ($item.EntryID) { $item.EntryID.ToString() } else { "no-id-$counter" }
              StoreID = if ($item.Session -and $item.Session.DefaultStore -and $item.Session.DefaultStore.StoreID) { 
                $item.Session.DefaultStore.StoreID.ToString() 
              } elseif ($item.Parent -and $item.Parent.StoreID) { 
                $item.Parent.StoreID.ToString() 
              } else { 
                try { $namespace.DefaultStore.StoreID.ToString() } catch { "" }
              }
              Subject = $subject
              Sender = $sender
              Recipients = @()
              Body = $body
              ReceivedTime = $timeStamp
              IsRead = if (${folderType} -eq 5) { $true } else { -not $item.UnRead }
              HasAttachments = $item.Attachments.Count -gt 0
            }
            
            $counter++
          } catch { $counter++; continue }
        }
        
        if ($emails.Count -eq 0) { Write-Output "[]" } 
        else { Write-Output ($emails | ConvertTo-Json -Depth 2 -Compress) }
        
      } catch {
        Write-Output ([PSCustomObject]@{ error = $_.Exception.Message; type = "OutlookConnectionError" } | ConvertTo-Json -Compress)
      }
    `;
  
    try {
      const result = await this.executePowerShell(script);
      if (!result || result.trim() === '') return [];
      
      const cleanResult = result.replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g, '').trim();
      const parsed = JSON.parse(cleanResult);
      
      if (parsed.error) throw new Error(`Outlook Error: ${parsed.error}`);
      
      const emailArray = Array.isArray(parsed) ? parsed : [parsed];
      return emailArray.map((item: any) => ({
        id: this.cleanText(item.Id || ''),
        storeId: this.cleanText(item.StoreID || ''),
        subject: this.cleanText(item.Subject || 'No Subject'),
        sender: this.cleanText(item.Sender || 'Unknown'),
        recipients: [],
        body: this.cleanText(item.Body || ''),
        receivedTime: new Date(item.ReceivedTime),
        isRead: Boolean(item.IsRead),
        hasAttachments: Boolean(item.HasAttachments)
      }));
      
    } catch (error) {
      console.error('Email fetch failed:', error);
      return [{
        id: 'fallback-1',
        storeId: '',
        subject: 'Email content unavailable',
        sender: 'system@outlook.com',
        recipients: [],
        body: 'Unable to retrieve email content.',
        receivedTime: new Date(),
        isRead: true,
        hasAttachments: false
      }];
    }
  }

• src/outlook-manager.ts:3-13 (schema)

  TypeScript interface defining the structure of EmailMessage objects returned by get_inbox_emails.

  export interface EmailMessage {
    id: string;
    storeId?: string;
    subject: string;
    sender: string;
    recipients: string[];
    body: string;
    receivedTime: Date;
    isRead: boolean;
    hasAttachments: boolean;
  }