Skip to main content
Glama
README.md
<div align="center">

<a href="https://glama.ai/mcp/servers/@titanzero/outlook-mcp">
  <img width="380" height="200" src="https://glama.ai/mcp/servers/@titanzero/outlook-mcp/badge" alt="Outlook MCP on Glama" />
</a>

# Outlook MCP Server

**Let AI manage your Outlook inbox, calendar, contacts, tasks and rules — through natural language.**

Built on [Model Context Protocol](https://modelcontextprotocol.io) · Powered by [Microsoft Graph API](https://learn.microsoft.com/en-us/graph/overview)

[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D22-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![MCP SDK](https://img.shields.io/badge/MCP_SDK-1.32-blueviolet)](https://www.npmjs.com/package/@modelcontextprotocol/sdk)

</div>

---

## What is this?

This MCP server turns any compatible AI assistant into a full-featured **Outlook assistant**. Instead of clicking through the Outlook UI, just ask your AI:

> _"Show me unread emails from this week"_
> _"Schedule a meeting with Alice tomorrow at 3pm and check if she's free first"_
> _"Forward that email to my team and create a follow-up task"_
> _"Set my out-of-office until Friday"_

Your AI handles authentication, API calls, pagination, filtering — everything. You just talk.

---

## Capabilities

| Area            | Tools | What your AI can do                                                                                                                                 |
| --------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Email**       | 30    | List, search (basic + KQL), read (preview/full), send, reply/forward, delete, mark read/unread, manage drafts, attachments, **shared mailboxes**, **conversation threads**, **message recall**, **distribution lists**, **bulk operations**, **categorize/flag** |
| **Calendar**    | 33    | List calendars/events, create/update/accept/decline/cancel, **free/busy**, **meeting rooms & room lists**, **calendar groups**, **calendar view (expanded recurring)**, **merged view**, **reminders (snooze/dismiss/set)**, **online meetings (Teams)**, **calendar sharing & permissions** |
| **Folders**     | 25    | List hierarchy, create/move/rename/delete, **bulk operations (copy/move/delete/mark-read/flag/categorize)**, **folder permissions**, **statistics & search**, **hierarchy management (tree, move, create path, empty, path lookup)** |
| **Contacts**    | 26    | List/search (advanced filters), create (basic/full), update, delete, **contact folders (CRUD)**, **contact photos**, **contact lists/distribution lists**, **statistics & analytics** |
| **Mailbox**     | 23    | Settings, out-of-office, **working hours**, **delegates**, **language/region/date/time formats**, **mail tips (auto-reply, mailbox full, delivery restrictions)**, **user profile**, **mailbox usage** |
| **Tasks**       | 29    | Task lists, tasks, **steps/checklists**, **recurrence patterns**, **attachments**, **linked resources (emails, events)**, **categories (master list + task assignment)** |
| **Rules**       | 20    | List/create/update/delete, **advanced conditions (13 types) & actions (11 types)**, **rule templates (9 built-in)**, **test rule against email**, **bulk enable/disable**, **import/export (JSON)** |
| **Auth**        | 3     | OAuth 2.0 with automatic token refresh — authenticate once, use forever                                                                             |
| **Resources**   | 40    | Static resources + resource templates across email, calendar, contacts, folders, mailbox, tasks, rules                                              |
| **Prompts**     | 7     | Reusable prompt templates for common Outlook workflows                                                                                              |
| **Completions** | 9     | Argument completion handlers for folder names, event IDs, contact emails, and more                                                                  |

**195 tools, 40 resources, 7 prompts, 9 completions total.**

---

## Quick Start

```bash
# 1. Clone and install
git clone https://github.com/titanzero/outlook-mcp.git
cd outlook-mcp
npm install

# 2. Configure (see Azure Setup below)
cp .env.example .env
# Edit .env with your Azure credentials

# 3. Start the OAuth server and authenticate
npm run auth-server

# 4. Add to your MCP client config and start using!
```

---

## Azure App Setup

You need an Azure app registration to connect to Microsoft Graph.

<details>
<summary><strong>1. Register the App</strong></summary>

1. Open [Azure Portal → App registrations](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade)
2. Click **New registration**
3. Name: `Outlook MCP Server` (or anything you like)
4. Account type: **Accounts in any organizational directory and personal Microsoft accounts**
5. Redirect URI: **Web** → `http://localhost:3333/auth/callback`
6. Click **Register**
7. Copy the **Application (client) ID** → this is your `OUTLOOK_CLIENT_ID`

</details>

<details>
<summary><strong>2. Set API Permissions</strong></summary>

Go to **API permissions** → **Add a permission** → **Microsoft Graph** → **Delegated permissions**, then add:

- `offline_access`
- `User.Read`
- `Mail.Read`
- `Mail.ReadWrite`
- `Mail.Send`
- `Mail.Read.Shared`
- `Calendars.Read`
- `Calendars.ReadWrite`
- `Calendars.Read.Shared`
- `Contacts.Read`
- `Contacts.ReadWrite`
- `MailboxSettings.Read`
- `MailboxSettings.ReadWrite`
- `MailboxFolder.Read`
- `MailboxFolder.ReadWrite`
- `Tasks.ReadWrite`
- `Group.Read.All`

</details>

<details>
<summary><strong>3. Generate Client Secret</strong></summary>

1. Go to **Certificates & secrets** → **Client secrets** → **New client secret**
2. Set description and longest expiration
3. **Copy the secret VALUE** (not the Secret ID!)
4. This is your `OUTLOOK_CLIENT_SECRET`

</details>

---

## Configuration

### Environment Variables

Create `.env` in the project root:

```bash
OUTLOOK_CLIENT_ID=your-application-client-id
OUTLOOK_CLIENT_SECRET=your-client-secret-VALUE
```

> **Important:** Always use the secret **VALUE** from Azure, not the Secret ID.

### MCP Client Configuration

Add to your MCP client config (e.g., `claude_desktop_config.json`, VS Code settings, etc.):

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

See [AGENTS.md](./AGENTS.md) for client-specific examples.

### Advanced

Edit `config.js` to customize server name, timezone, pagination limits, field selections, and response format (`toon` or `text`).

---

## Authentication Flow

```
You ──ask AI──▸ "authenticate"
                        │
AI returns URL ◂────┘
                        │
You open URL in browser ▸ Microsoft login ▸ Grant permissions
                                                    │
                        ┌───────────────────────────┘
                        ▼
              OAuth callback on localhost:3333
              Tokens saved to ~/.outlook-mcp-tokens.json
              ✔ Auto-refresh — no re-auth needed
```

**Step 1** — Start the auth server (must be running before authenticating):

```bash
npm run auth-server
```

**Step 2** — Ask your AI to `authenticate`, open the URL, sign in, done.

Tokens persist in `~/.outlook-mcp-tokens.json` and refresh automatically.

---

## Project Structure

```
index.js                  ── MCP entry point (McpServer with resources, prompts, completions)
config.js                 ── centralized constants & settings
outlook-auth-server.js    ── standalone OAuth server

auth/                     ── authentication & token management
email/                    ── list, search, read, send, reply, forward, delete,
│                            mark-as-read, attachments, drafts,
│                            shared-mailbox, groups, conversations, recall, kql-search
calendar/                 ── list, create, accept, decline, cancel, delete,
│                            sharing, rooms, groups, view, reminders, online-meetings
folder/                   ── list, create, move, bulk-operations, permissions,
│                            statistics, hierarchy
contacts/                 ── list, create, update, delete, folders, photos,
│                            lists, search
mailbox/                  ── settings, out-of-office, working-hours,
│                            delegates, language-region, mail-tips
tasks/                    ── list, create, update, complete, delete,
│                            steps, recurrence, attachments, linked-resources, categories
rules/                    ── list, create, update, delete, edit-sequence,
│                            advanced, templates
prompts/                  ── 7 reusable prompt templates
completion/               ── 9 argument completion handlers

utils/
├── graph-client.js       ── Graph SDK wrapper with pagination
├── response-formatter.js ── TOON / plain-text output toggle
└── response-helpers.js   ── error detection & MCP response builders

scripts/                  ── CLI utilities & debug helpers
```

---

## Available Commands

| Command               | Description                                  |
| --------------------- | -------------------------------------------- |
| `npm install`         | Install dependencies                         |
| `npm start`           | Start the MCP server (stdio)                 |
| `npm run auth-server` | Start OAuth server on port 3333              |
| `npm run inspect`     | Launch MCP Inspector for interactive testing |
| `npm test`            | Run Jest test suite                          |
| `npm run debug`       | Print env vars and start server              |
| `npx kill-port 3333`  | Free port 3333 if occupied                   |

---

## Troubleshooting

<details>
<summary><strong>Cannot find module '@modelcontextprotocol/sdk'</strong></summary>

Run `npm install` first.

</details>

<details>
<summary><strong>EADDRINUSE: port 3333 already in use</strong></summary>

```bash
npx kill-port 3333
npm run auth-server
```

</details>

<details>
<summary><strong>Invalid client secret (AADSTS7000215)</strong></summary>

You're using the Secret **ID** instead of the Secret **Value**. Go to Azure Portal → Certificates & secrets → copy the **Value** column.

</details>

<details>
<summary><strong>Auth URL doesn't load / "site can't be reached"</strong></summary>

The auth server isn't running. Start it first with `npm run auth-server`, then retry.

</details>

<details>
<summary><strong>"Authentication required" after setup</strong></summary>

Token may be expired or corrupted. Delete `~/.outlook-mcp-tokens.json` and re-authenticate.

</details>

<details>
<summary><strong>Server doesn't start in Claude Desktop</strong></summary>

1. Verify the absolute path to `index.js` in your Claude Desktop config
2. Ensure `OUTLOOK_CLIENT_ID` and `OUTLOOK_CLIENT_SECRET` are set
3. Restart Claude Desktop after config changes

</details>

---

## Extending the Server

Adding a new tool is straightforward:

1. Create a handler file in the appropriate module directory
2. Export `{ name, description, inputSchema, handler }`
3. Add it to the module's `index.js` exports
4. It's automatically registered via `index.js` at the root

See [AGENTS.md](./AGENTS.md#extending-the-server) for the full checklist.

---

## License

[MIT](LICENSE)

TDQS

A3.5/5.0

Scored across 20 tools

Disambiguation5/5

Each tool has a clearly distinct purpose with no ambiguity, such as accept-event vs. decline-event for calendar responses, or list-emails vs. search-emails for email retrieval. The descriptions reinforce distinct actions on specific resources like events, emails, folders, and rules, ensuring agents can easily differentiate between tools.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern with hyphens, such as create-event, list-folders, and mark-as-read. There are no deviations in naming conventions, making the set predictable and easy to parse for agents.

Tool Count4/5

With 20 tools, the count is slightly high but reasonable for the Outlook domain, covering email, calendar, folders, and rules comprehensively. It includes core CRUD operations and management functions, though it might be borderline for some use cases due to the breadth.

Completeness5/5

The tool surface provides complete coverage for the Outlook domain, including CRUD operations for events, emails, folders, and rules, along with authentication and status checks. There are no obvious gaps, as it supports full lifecycle management from creation to deletion and search capabilities.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues