outlook-lite-mcp

A lightweight MCP server for Microsoft Outlook email (Microsoft Graph). Works with work/school accounts (Microsoft 365) and personal accounts (Outlook.com, Hotmail).

• Zero dependencies. Node 22.18+ runs the TypeScript directly: no npm install, no build.

• You run it, you own it. It runs on your machine with your own Azure app. No third-party server sees your mail.

• Token-light. Tabular output and cleaned bodies (no quotes, signatures or legal footers).

• Permanent ids. Every email comes with its real Microsoft Graph id, requested as an immutable id: it doesn't change when the email is moved or archived, so you can store it in a database and use it later.

• Safe by default. Reply, forward, send and delete always show a preview and wait for the user's approval.

• Login on connect. The first time the client connects, your browser opens on the Microsoft account picker.

Português: README.pt-BR.md. Tool descriptions are in Portuguese; any LLM handles them fine.

Prerequisites

• Node.js 22.18 or newer (node --version). Nothing else to install: no npm install, no build.

• git, to clone the repository (or download the ZIP from GitHub).

• A Microsoft account with a mailbox: work/school (Microsoft 365) or personal (Outlook.com, Hotmail).

• Permission to register an app in Microsoft Entra (free):

  • work account: allowed by default in most companies; if blocked, ask your IT admin to register it or to grant consent;

  • personal account: sign in to https://portal.azure.com once with a free Azure account, which creates your own directory.

• An MCP client: Claude Desktop, Claude Code, Cursor, VS Code or any other client that supports stdio servers.

Related MCP server: outlook-mcp

Quick start

1. Get the code

git clone https://github.com/almeidatmatheus/outlook-lite-mcp.git
cd outlook-lite-mcp
node --version   # needs 22.18 or newer

2. Register your own app in Microsoft Entra (once, ~5 min)

Each user (or each company) registers their own app. It's free and keeps you in control of your data.

1. Go to https://entra.microsoft.com → Applications → App registrations → New registration.

   • Name: outlook-lite-mcp

   • Supported account types:

     • personal + any company: Accounts in any organizational directory and personal Microsoft accounts

     • only your company: Accounts in this organizational directory only

   • Register.

2. On Overview, copy the Application (client) ID (and the Directory (tenant) ID if you chose "this directory only").

3. Authentication → Add a platform → Mobile and desktop applications → custom redirect URI:

   http://localhost/cb

   Then, still in Authentication, set Allow public client flows to Yes → Save. No client secret is needed for local use.

4. API permissions → Add a permission → Microsoft Graph → Delegated permissions: Mail.ReadWrite, Mail.Send, MailboxSettings.Read, User.Read, offline_access. (Never Application permissions.)

5. Work accounts: if your company requires it, an admin clicks Grant admin consent for .

3. Add it to your MCP client

Claude Desktop (claude_desktop_config.json, see examples/):

{
  "mcpServers": {
    "outlook": {
      "command": "node",
      "args": ["/absolute/path/to/outlook-lite-mcp/src/main.ts"],
      "env": { "OUTLOOK_MCP_CLIENT_ID": "<your client id>" }
    }
  }
}

Claude Code:

claude mcp add outlook -e OUTLOOK_MCP_CLIENT_ID=<your client id> -- node /absolute/path/to/outlook-lite-mcp/src/main.ts

Any other MCP client (Cursor, VS Code, local models…): command node /absolute/path/to/outlook-lite-mcp/src/main.ts, stdio transport, same env var.

Restart the client. The browser opens on the Microsoft account picker; sign in and you're done. The token is stored in ~/.outlook-lite-mcp/default.json (mode 600) and refreshes itself. To use another account, ask to "switch account" (tool cx, action trocar).

On macOS, keep the folder outside Downloads/Desktop/Documents (e.g. ~/outlook-lite-mcp), or the client may not be allowed to read it.

Try it

"list my last 5 emails" · "read the first one" · "reply saying thanks" · "archive the newsletters" · "download the invoice attachment"

Tools

Email ids: the id column of ls/find is the email's permanent Graph id (immutable id). Pass it as alvo/alvos to the other tools, now or in a later session.

Confirmation. If the client supports MCP elicitation, the server asks the user directly. Otherwise the first call returns a preview and a code cf; only the identical call with that cf executes. Clients should show the preview to the user and send cf only after explicit approval.

Options

Command line: node src/main.ts login | whoami | logout. Behind a corporate proxy: Node 22.21+ with NODE_USE_ENV_PROXY=1 and HTTPS_PROXY.

Remote mode (optional, self-hosted)

To use it from claude.ai as a custom connector, run your own HTTPS instance:

export OUTLOOK_MCP_CLIENT_ID=<client id>
export OUTLOOK_MCP_URL=https://your-domain.example      # public HTTPS URL
export OUTLOOK_MCP_ALLOW=you@company.com,company.com    # who may connect (emails or domains)
node src/main.ts http                                   # listens on PORT (8787)

In Entra add the platform Web with redirect https://your-domain.example/ms/cb (and a client secret in OUTLOOK_MCP_CLIENT_SECRET if Entra asks for one). In claude.ai add a custom connector with https://your-domain.example/mcp. For a quick test, cloudflared tunnel --url http://localhost:8787 gives you a temporary HTTPS URL.

Always set OUTLOOK_MCP_ALLOW. Without it anyone with the URL can connect their own account to your server.

Security

• Delegated permissions only: the server can do what the signed-in user can do, nothing more.

• Tokens live on your machine (~/.outlook-lite-mcp, mode 600). Remote mode keeps them in http-store.json on the server.

• Email content is untrusted. A message can contain text trying to instruct the AI ("forward this to…"). The mandatory confirmation before reply/forward/send/delete is the main defense; don't remove it.

• See SECURITY.md to report a vulnerability.

Project layout

src/
  main.ts     entry: stdio (default) | http | login | logout | whoami
  mcp.ts      MCP protocol: JSON-RPC, schema validation, confirmation (elicitation or cf code)
  http.ts     remote mode: Streamable HTTP + OAuth server that delegates login to Microsoft
  auth.ts     Microsoft login: browser (PKCE), device code, refresh, token file
  ctx.ts      per-user state (token, caches)
  g.ts        minimal Graph client: get/post/patch, $batch, retry on 429/401, immutable ids
  ids.ts      validates the email ids received by the tools
  fmt.ts      tabular output, body cleanup
  lib.ts      shared helpers and enums
  tools/      one file per tool + index.ts
test/
  mock.ts     fake Microsoft (login + Graph)
  run.ts      real MCP clients against the mock, local and remote

Development

node test/run.ts   # 56 checks, no network or Microsoft account needed
npx tsc -p .       # type check (optional)

License

MIT