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

{
  "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).

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_add_attachment`	Attach a local file to a draft/message (does not send)
`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