Polaralias/Outlook-MCP-Server

Outlook-MCP-Server

Model Context Protocol (MCP) server that bridges Outlook mail and calendar data from Microsoft 365 into MCP compatible clients. The server authenticates with Microsoft Graph, exposes curated tools for working with messages and events, and stores access tokens locally for subsequent sessions.

Table of contents

• Architecture overview
• Getting started
  • Azure app registration
  • Environment variables
  • Local setup
• Authentication flow
• Tool reference
• Usage examples
• Troubleshooting
• Security notes
• Additional documentation
• Contributing
• License

Architecture overview

The server is organised into small, purpose-built modules:

Incoming MCP requests are routed to the relevant tool handler. Handlers fetch Microsoft Graph access tokens through the authenticator, create scoped Graph clients, and return structured responses to the MCP client.

Getting started

Azure app registration

1. Sign in to the Azure portal with a tenant that can access Microsoft Graph.
2. Navigate to Azure Active Directory → App registrations → New registration.
3. Choose a descriptive name (for example, Outlook MCP Server) and register the application as a single-tenant app unless multiple tenants are required.
4. Record the Application (client) ID and the Directory (tenant) ID for later use.
5. Under Certificates & secrets, create a client secret if you plan to use confidential client flows (not required for device code, but recommended for automation scenarios).
6. In API permissions, add delegated permissions for:
   • Mail.ReadWrite
   • Mail.Send
   • Calendars.ReadWrite
   • offline_access
   • Any additional Microsoft Graph scopes you plan to request. Grant admin consent for your tenant.

Environment variables

Configuration is managed through environment variables at runtime. Provide the following values before starting the server (see for details, defaults, and validation rules):

Local setup

1. Clone this repository and install dependencies:

   npm install
   

2. Create a .env file (or export variables in your shell) with the environment variables listed above.
3. Build the TypeScript sources or run the server in development mode:

   # Build for production output in dist/
   npm run build
   
   # Or run directly with ts-node for rapid iteration
   npm run dev
   

4. Start the MCP server (from the compiled output) and connect with your MCP-compatible client:

   npm start
   

Authentication flow

The server uses the Microsoft identity platform device code flow:

1. On startup the server initialises DeviceFlowAuthenticator with your configured tenants and scopes.
2. When authentication is required, the authenticator requests a device code and emits it through the device_code event. The server logs the verification URL and user code so you can complete the sign-in on another device or browser.
3. After you authenticate and grant the requested Microsoft Graph scopes, the authenticator exchanges the device code for access and refresh tokens.
4. Tokens are encrypted with MCP_TOKEN_SECRET and stored at MCP_TOKEN_PATH via TokenStore. Subsequent requests reuse the cached tokens and refresh them automatically when near expiry.
5. Each tool execution resolves the target tenant, obtains an authorised Microsoft Graph client, and performs the requested operation.

Tool reference

The following MCP tools are available:

Health

Mail

Calendar

Refer to the inline TypeScript docstrings for detailed parameters and response shapes.

Usage examples

Example MCP client invocation using the Model Context Protocol CLI:

# Start the server (assumes environment variables are set)
npm run dev

# In a separate shell, query the health status
echo '{"method":"tools.call","params":{"name":"health.status","arguments":{}}}' \
  | npx @modelcontextprotocol/cli

Example email search request payload:

{
  "method": "tools.call",
  "params": {
    "name": "email.search",
    "arguments": {
      "query": "from:someone@example.com",
      "top": 10,
      "tenantId": "<tenant-id>"
    }
  }
}

Troubleshooting

• MCP_CLIENT_ID must be provided – The required environment variable is missing. Verify your .env file or shell exports.
• Authentication succeeds but tool calls fail with Tenant ... is not configured – Ensure the tenantId you pass to a tool matches one of the IDs listed in MCP_TENANT_IDS.
• Expired or invalid tokens – Delete the file at MCP_TOKEN_PATH to force re-authentication. Confirm MCP_TOKEN_SECRET has not changed between runs.
• insufficient privileges errors from Microsoft Graph – Review your Azure app registration and confirm admin consent was granted for the requested scopes.
• Network or proxy restrictions – The device code flow requires outbound HTTPS access to login.microsoftonline.com and graph.microsoft.com.

Security notes

• Store MCP_TOKEN_SECRET in a secure secret manager or environment injection tool; never commit it to version control.
• Consider restricting MCP_TENANT_IDS and MCP_DEFAULT_USER_ID to service accounts instead of personal mailboxes.
• Regularly rotate the Azure client ID and regenerate secrets when rotating credentials.
• The token cache (MCP_TOKEN_PATH) contains encrypted refresh tokens; ensure the file permissions restrict access to the service user.
• When adding scopes via MCP_SCOPES, request the minimum permissions necessary for your workflow.

Additional documentation

Contributing

We welcome issues and pull requests! See for development workflows, coding standards, and testing guidance.

License

This project is licensed under the terms of the .