home / mcp / modular outlook mcp server

Modular Outlook MCP Server

Provides OAuth-authenticated access to Outlook data via MCP enabling email and calendar actions.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "ryaker-outlook-mcp": {
      "command": "node",
      "args": [
        "/absolute/path/to/outlook-mcp/index.js"
      ],
      "env": {
        "USE_TEST_MODE": "false",
        "OUTLOOK_CLIENT_ID": "your-client-id-here",
        "OUTLOOK_CLIENT_SECRET": "your-client-secret-here"
      }
    }
  }
}

You can connect Claude to your Microsoft Outlook data through a modular MCP server that handles authentication and provides email and calendar actions via the Microsoft Graph API. This MCP server is designed for clean separation of concerns, easy maintenance, and testable interactions with Outlook data.

How to use

You run the local MCP server configuration and connect Claude through an MCP client. The server exposes tools for managing your Outlook data, including reading and sending emails and handling calendar events. To start using it, you configure Claude Desktop to point at your local MCP server, authenticate with Microsoft, and then invoke the available Outlook tools from Claude to interact with your mailbox and calendar.

How to install

Prerequisites: you need Node.js 14.0.0 or higher and npm (or yarn) installed on your system. You also need an Azure account to register an app for Microsoft Graph access.

Install dependencies for the MCP server project:

npm install

If you are using a local MCP command configuration, the following snippet describes how the server can be started via a stdio configuration. Use your absolute path to the MCP index file in your setup.

{
  "type": "stdio",
  "name": "outlook_mcp",
  "command": "node",
  "args": ["/absolute/path/to/outlook-mcp/index.js"],
  "env": {
    "USE_TEST_MODE": "false",
    "OUTLOOK_CLIENT_ID": "your-client-id-here",
    "OUTLOOK_CLIENT_SECRET": "your-client-secret-here"
  }
}

Configuration

Environment variables you will configure for the MCP server are used to connect to Azure and control test mode. Create a .env file in the project root with these values.

# Get these values from your Azure App Registration
USE_TEST_MODE=false
OUTLOOK_CLIENT_ID=your-client-id-here
OUTLOOK_CLIENT_SECRET=your-client-secret-here

Security and authentication

The server relies on OAuth 2.0 with Microsoft Graph. Tokens are obtained through the authentication flow initiated from Claude Desktop and are stored locally for reuse. Ensure you keep client secrets confidential and rotate them periodically in Azure.

Notes

The server is designed with a modular structure. Authentication, calendar, email, and utility helpers live in separate modules to simplify maintenance and testing.

Troubleshooting

If you encounter issues starting the authentication flow, verify that the authentication server is running and that the environment variables are correctly set in both your local environment and Claude Desktop configuration.

Extending the server

To add or modify functionality, create new module directories (for example, calendar or email), implement handlers for the new tools, export them from module index files, and wire them into the main server entry. This keeps changes isolated and maintainable.

Available tools

authenticate

Initiate OAuth flow to obtain tokens for Microsoft Graph access via Claude Desktop

email.list

List emails in the connected mailbox

email.read

Read a specific email by ID or query

email.search

Search emails by keywords or filters

email.send

Send an email using the connected account

calendar.list

List calendar events for the connected account

calendar.create

Create a new calendar event

calendar.accept

Accept an event invite

calendar.decline

Decline a calendar invite

calendar.tentative

Tentatively accept a calendar invite

calendar.delete

Delete a calendar event