Microsoft Outlook MCP Server

MCP server for Microsoft Outlook — search, send, and manage mail and calendar with browser-session auth; no Azure AD app registration.

Clone the repo, build it, point your AI tool at dist/index.js. Uses the same OWA REST API that Outlook Web App calls internally. Auth is your normal Outlook browser login; access matches what your account can already do.

Prerequisites

• Node.js 18+
• Microsoft 365 / Outlook.com account
• Chrome (macOS/Linux) or Edge (Windows)

Setup

git clone https://github.com/hickeroar/outlook-mcp.git
cd outlook-mcp
npm install
npm run build

Register as a local stdio MCP server:

{
  "mcpServers": {
    "Outlook": {
      "command": "node",
      "args": ["/absolute/path/to/outlook-mcp/dist/index.js"]
    }
  }
}

Session files: ~/.outlook-mcp-server/ (macOS/Linux) or %APPDATA%\outlook-mcp-server\ (Windows).

First login

Call outlook_login (use forceNew: true if session is dead). Browser opens for Microsoft sign-in. After that, tools use cached OWA tokens with automatic refresh.

Commands

npm run build
npm run typecheck
npm run cli -- status
npm run cli -- login
npm run cli -- inbox
npm run cli -- search "quarterly report"
npm run cli -- calendar

MCP Resources

URI	Description
outlook://me/profile	Signed-in user profile
outlook://status	Token and session status
outlook://me/inbox	Recent inbox messages (last 10)

Tools

Authentication

Tool	Description
outlook_login	Login via browser (headless SSO first)
outlook_status	Auth and token diagnostics

Mail

Tool	Description
outlook_list_folders	List mail folders
outlook_list_messages	List messages in a folder
outlook_search_messages	Search mail by keyword
outlook_get_message	Get full message by ID
outlook_send_message	Send email immediately
outlook_create_draft	Create draft without sending
outlook_create_reply_draft	Create reply draft (set send=true to send)
outlook_create_reply_all_draft	Create reply-all draft
outlook_create_forward_draft	Create forward draft
outlook_update_message	Update draft or message properties
outlook_mark_read	Mark read/unread
outlook_send_draft	Send existing draft
outlook_move_message	Move to another folder
outlook_delete_message	Delete (moves to Deleted Items)

Calendar

Tool	Description
outlook_list_calendars	List calendars
outlook_get_calendar_view	Events in date range
outlook_get_event	Single event by ID
outlook_create_event	Create event
outlook_update_event	Update event
outlook_delete_event	Delete event
outlook_cancel_event	Cancel meeting (organiser)
outlook_respond_event	Accept/decline/tentative RSVP
outlook_list_event_instances	Recurring event instances

Write tools (send, reply, delete, cancel, etc.) execute immediately. Confirm with the user before calling.

Architecture

src/
├── auth/           # Token extraction, refresh, encryption
├── browser/        # Playwright login (persistent profile)
├── api/            # OWA REST clients (mail, calendar, service.svc)
├── tools/          # MCP tool handlers
├── utils/          # HTTP, parsers, api-config
└── server.ts       # OutlookServer MCP class

See docs/API-REFERENCE.md and docs/SESSION-DATA-REFERENCE.md for API and session details.

License

MIT