mcp-outlook-lite

The lightest way to connect AI agents to Microsoft Outlook. No client secret. No complex OAuth. Just a Client ID and you're done.

Tired of getting stuck on Outlook MCP auth? Most Outlook MCP servers require client secrets, complex permission grants, and multi-step OAuth configurations that break silently. This one uses PKCE — the browser handles login, no secrets stored anywhere. If you can create an Azure app registration, you can use this.

Why this one?

The auth problem is real. If you've tried other Outlook MCPs and got stuck after creating the Azure app — authorization failures, redirect URI mismatches, token exchange errors — that's because they use flows designed for server apps. PKCE is designed for exactly this use case: local tools that can't store secrets.

Related MCP server: m365-mcp-server

3-step setup

Step 1: Register an Azure app (5 min, one-time)

1. Azure Portal > App registrations > New registration

2. Name: anything (e.g. Outlook MCP). Account type:

   • Work/school: "Accounts in this organizational directory only"

   • Personal: "Accounts in any org directory and personal Microsoft accounts"

3. Redirect URI: Web > http://localhost/callback

4. Authentication > enable Allow public client flows > Save

5. API permissions > Add Microsoft Graph delegated permissions:

   Mail.Read  Mail.ReadWrite  Mail.Send  Calendars.Read  Calendars.ReadWrite
   User.Read  MailboxSettings.Read  Files.Read.All  Sites.Read.All  offline_access

6. Copy Application (client) ID from the Overview page

7. Determine your Tenant ID:

   • Personal account (outlook.com / hotmail.com / live.com): use consumers

   • Work/school account: use the Directory (tenant) ID from the Overview page

   • Both: use common

That's it. No client secret. No certificates. No admin consent (for personal accounts).

⚠️ Personal account users: You must set AZURE_TENANT_ID=consumers. Using the Directory (tenant) ID from Azure Portal will authenticate successfully but Graph API calls will return 401 because your mailbox lives in the consumer identity system, not in that Azure AD tenant.

Step 2: Install

npx mcp-outlook-lite

Or add to your MCP client config:

# Personal account (outlook.com / hotmail.com / live.com)
claude mcp add outlook \
  -e AZURE_CLIENT_ID=your-client-id \
  -e AZURE_TENANT_ID=consumers \
  -- npx mcp-outlook-lite

# Work/school account
claude mcp add outlook \
  -e AZURE_CLIENT_ID=your-client-id \
  -e AZURE_TENANT_ID=your-directory-tenant-id \
  -- npx mcp-outlook-lite

{
  "mcpServers": {
    "outlook": {
      "command": "npx",
      "args": ["mcp-outlook-lite"],
      "env": {
        "AZURE_CLIENT_ID": "your-client-id",
        "AZURE_TENANT_ID": "consumers"
      }
    }
  }
}

Replace consumers with your Directory (tenant) ID for work/school accounts.

{
  "mcpServers": {
    "outlook": {
      "command": "npx",
      "args": ["mcp-outlook-lite"],
      "env": {
        "AZURE_CLIENT_ID": "your-client-id",
        "AZURE_TENANT_ID": "consumers"
      }
    }
  }
}

Replace consumers with your Directory (tenant) ID for work/school accounts.

Step 3: Use it

The first tool call triggers auth automatically:

• Desktop: browser opens for Microsoft login

• SSH / container: device code printed to stderr — follow the link

After that, tokens refresh silently. No re-login between sessions.

46 tools, 6 categories

Example prompts

"Show me unread emails from this week"
"Find all emails from Alice about the budget"
"Reply to that email thanking her for the update"
"What meetings do I have tomorrow?"
"Schedule a 30-min call with Bob next Tuesday at 2pm"
"Download and summarize the PDF from the latest Finance email"

How PKCE auth works

Agent calls a tool
       |
       v
  Token cached?  ---yes--->  Use it
       | no
  Refresh works? ---yes--->  Silent refresh (no browser)
       | no
  PKCE flow:
    1. Generate code_verifier + code_challenge
    2. Browser opens -> Microsoft login
    3. Redirect to localhost with auth code
    4. Exchange code + verifier for tokens
    5. Encrypt and store tokens locally

No client secret anywhere in this flow. The PKCE challenge/verifier pair cryptographically proves the caller's identity. Tokens are encrypted at rest using the OS keychain or AES-256 with a random key.

Configuration

Development

TypeScript with noImplicitAny. 769 tests, 81% coverage.

npm test              # Run tests
npm run typecheck     # Type check
npm run build         # Compile to dist/
npm run dev           # Dev mode with tsx

server/
  index.ts              # MCP server entry
  types.ts              # Shared interfaces
  auth/                 # PKCE + device code auth
  graph/                # Microsoft Graph client with rate limiting
  tools/                # 46 tool handlers
  schemas/              # MCP tool schemas
  utils/                # Validation, caching, error handling
  tests/                # 769 tests

Security

• Tokens encrypted at rest (OS keychain or AES-256)

• All Graph API calls scoped to /me/ (your mailbox only)

• No sensitive data in tool responses

• Recipient validation before sending emails

Report vulnerabilities via GitHub private reporting. See SECURITY.md.

See Also

outlook-cli-skill — Lightweight alternative by the same author. No MCP server needed — a thin CLI handles OAuth, and AI agents call Microsoft Graph API directly via skill files. Works with any AI agent (Claude Code, Cursor, Codex, Gemini), not just MCP clients.

License

MIT