Mcp Outlook
Outlook integration with OAuth, message search, batch operations, and calendar management
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"]
}
}
}
HTTP
{
"mcpServers": {
"outlook": {
"type": "http",
"url": "http://localhost:9003/mcp",
"start": {
"command": "npx",
"args": ["-y", "@mcp-z/mcp-outlook", "--port=9003"]
}
}
}
}
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
- Go to Azure Portal.
- Navigate to Azure Active Directory > App registrations.
- Click New registration.
- Choose a name and select a supported account type.
- Copy the Application (client) ID and Directory (tenant) ID.
- 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/callbackURL. Local HTTP uses the port configured with--portorPORT. - For local hosting, add
http://localhostfor the ephemeral redirect URL.
- 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
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"
}
}
}
}
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"
}
}
}
}
}
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"
}
}
}
}
DCR (self-hosted)
HTTP only. Requires a public base URL. CSV export and /files are disabled in DCR mode; resourceStoreUri is ignored.
From the project's README.