@mcp-z/mcp-outlook

MCP server for Outlook integration with OAuth authentication, message search, and batch operations

Requires Node.js >=20. The examples use npx, included with npm, to run this server and @mcp-z/cli.

Common uses

• Search and read messages
• Send and reply to emails
• Manage categories and export messages to CSV

Transports

MCP supports stdio and HTTP.

Both the 2025 and 2026-07-28 protocol revisions are served, over either transport, from the same server. Your client negotiates whichever it speaks. A 2025 client keeps working with no change, and support for it is not being dropped. The 2026-07-28 revision is stateless, so a client speaking it sends no initialize handshake and carries no session id.

Stdio

{
  "mcpServers": {
    "outlook": {
      "command": "npx",
      "args": ["-y", "@mcp-z/mcp-outlook"]
    }
  }
}
Copy

HTTP

{
  "mcpServers": {
    "outlook": {
      "type": "http",
      "url": "http://localhost:9003/mcp",
      "start": {
        "command": "npx",
        "args": ["-y", "@mcp-z/mcp-outlook", "--port=9003"]
      }
    }
  }
}
Copy

start is an extension used by npx @mcp-z/cli up to launch HTTP servers for you. The HTTP endpoint is /mcp.

Create a Microsoft app

1. Go to Azure Portal.
2. Navigate to Azure Active Directory > App registrations.
3. Click New registration.
4. Choose a name and select a supported account type.
5. Copy the Application (client) ID and Directory (tenant) ID.
6. Select the credential platform that matches your transport:
   • For stdio, choose "Mobile and desktop applications" under Authentication and add the loopback redirect URI.
   • For HTTP, choose "Web" and add your public /oauth/callback URL. Local HTTP uses the port configured with --port or PORT.
   • For local hosting, add http://localhost for the ephemeral redirect URL.
7. Enable OAuth2 scopes in API Permissions: openid profile offline_access https://graph.microsoft.com/User.Read https://graph.microsoft.com/Mail.ReadWrite https://graph.microsoft.com/Mail.Send https://graph.microsoft.com/MailboxSettings.ReadWrite

OAuth modes

Configure via environment variables or the env block in .mcp.json. See server.json for the full list of options.

Loopback OAuth (default)

Environment variables:

MS_CLIENT_ID=your-client-id
MS_TENANT_ID=common
MS_CLIENT_SECRET=your-client-secret
Copy

Example (stdio) - Create .mcp.json:

{
  "mcpServers": {
    "outlook": {
      "command": "npx",
      "args": ["-y", "@mcp-z/mcp-outlook"],
      "env": {
        "MS_CLIENT_ID": "your-client-id",
        "MS_TENANT_ID": "common"
      }
    }
  }
}
Copy

Example (http) - Create .mcp.json:

{
  "mcpServers": {
    "outlook": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "start": {
        "command": "npx",
        "args": ["-y", "@mcp-z/mcp-outlook", "--port=3000"],
        "env": {
          "MS_CLIENT_ID": "your-client-id",
          "MS_TENANT_ID": "common"
        }
      }
    }
  }
}
Copy

Local (default): omit REDIRECT_URI → ephemeral loopback. Cloud: set REDIRECT_URI to your public /oauth/callback and expose the service publicly.

Note: the start block is a helper in npx @mcp-z/cli up for starting an HTTP server from your .mcp.json. See @mcp-z/cli for details.

Device code

Useful for headless or remote environments.

{
  "mcpServers": {
    "outlook": {
      "command": "npx",
      "args": ["-y", "@mcp-z/mcp-outlook", "--auth=device-code"],
      "env": {
        "MS_CLIENT_ID": "your-client-id",
        "MS_TENANT_ID": "common"
      }
    }
  }
}
Copy

DCR (self-hosted)

HTTP only. Requires a public base URL. CSV export and /files are disabled in DCR mode; resourceStoreUri is ignored.

{
  "mcpServers": {
    "outlook-dcr": {
      "command": "npx",
      "args": [
        "-y",
        "@mcp-z/mcp-outlook",
        "--auth=dcr",
        "--port=3456",
        "--base-url=https://oauth.example.com"
      ],
      "env": {
        "MS_CLIENT_ID": "your-client-id",
        "MS_TENANT_ID": "common",
        "MS_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}
Copy

How to use

# List tools
npx -y @mcp-z/cli inspect --servers outlook --tools

# Call a tool
npx -y @mcp-z/cli call-tool outlook message-search '{"query":"from:alice@example.com"}'
Copy

Tools

1. categories-list
2. label-add
3. label-delete
4. labels-list
5. message-get
6. message-mark-read
7. message-move-to-trash
8. message-respond
9. message-search
10. message-send
11. messages-export-csv

Resources

1. email

Prompts

1. draft-email
2. query-syntax

Configuration reference

See server.json for all supported environment variables, CLI arguments, and defaults.

Storage backends

OAuth tokens (TOKEN_STORE_URI) and DCR registrations (DCR_STORE_URI) are stored through keyv-registry, which picks an adapter from the URI protocol.

file:// (the default, under ~/.mcp-z/) and memory:// work with no extra setup.

Any other backend needs its adapter installed alongside this server. Adapters are resolved with require(), so a globally installed server finds a globally installed adapter:

npm install -g @mcp-z/mcp-outlook @keyv/redis

TOKEN_STORE_URI=redis://localhost:6379 mcp-outlook
Copy

A protocol whose adapter is missing fails at startup naming the package to install.

Documentation

API Docs