Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/eesb99/office365-mcp-server

Complete Microsoft Graph API integration for Claude Code CLI with 45 powerful Office 365 tools - Email, Calendar, Files, Contacts, Teams, Tasks
https://github.com/eesb99/office365-mcp-server

calendar claude-code email-management mcp-server microsoft-graph nodejs office365 onedrive teams

Last synced: about 2 months ago
JSON representation

Complete Microsoft Graph API integration for Claude Code CLI with 45 powerful Office 365 tools - Email, Calendar, Files, Contacts, Teams, Tasks

Awesome Lists containing this project

README 

          
# Office 365 MCP Server



> **Complete Microsoft Graph API integration for Claude Code CLI with 45 powerful Office 365 tools**



[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)

[![MCP Protocol](https://img.shields.io/badge/MCP-2024--11--05-blue)](https://modelcontextprotocol.io)

[![Tested](https://img.shields.io/badge/Tested-Claude%20Code%20CLI-purple)](https://claude.com/claude-code)



Seamlessly integrate your Office 365 account with Claude Code CLI for intelligent email management, calendar operations, file handling, and more. Built using the official Model Context Protocol (MCP) SDK.



---



## ✨ Features



- 📧 **Email Management** - 16 tools for reading, searching, organizing, and sending emails

- 📅 **Calendar Operations** - 9 tools for managing events and schedules

- 📁 **OneDrive Files** - 8 tools for file and folder management

- 👥 **Contacts** - 4 tools for contact management

- 💬 **Microsoft Teams** - 5 tools for team collaboration

- ✅ **Tasks & To-Do** - 4 tools for task management

- 🔐 **Secure** - Environment variable configuration, no hardcoded credentials

- ⚡ **Fast** - Built on official MCP SDK for optimal performance



**Total: 45 Production-Ready Tools**



---



## 📋 Table of Contents



- [Requirements](#requirements)

- [Installation](#installation)

- [Azure Configuration](#azure-configuration)

- [Claude Code CLI Setup](#claude-code-cli-setup)

- [Usage](#usage)

- [Available Tools](#available-tools)

- [Testing](#testing)

- [Security](#security)

- [Troubleshooting](#troubleshooting)

- [Contributing](#contributing)

- [License](#license)



---



## 🔧 Requirements



- **Node.js** 18.0.0 or higher

- **Claude Code CLI** installed and configured

- **Microsoft 365 Account** (Office 365)

- **Azure AD Application** with appropriate permissions

- **Admin Consent** for your Azure AD tenant



---



## 📦 Installation



### 1. Clone the Repository



```bash

git clone https://github.com/eesb99/office365-mcp-server.git

cd office365-mcp-server

```



### 2. Install Dependencies



```bash

npm install

```



Required packages:

- `@modelcontextprotocol/sdk` - Official MCP SDK

- `@azure/msal-node` - Microsoft Authentication Library

- `@microsoft/microsoft-graph-client` - Microsoft Graph API client

- `zod` - Schema validation



### 3. Configure Environment Variables



Copy the example configuration:



```bash

cp .env.example .env

```



Edit `.env` with your Azure credentials (see [Azure Configuration](#azure-configuration) below):



```bash

AZURE_CLIENT_ID=your-client-id-here

AZURE_AUTHORITY=https://login.microsoftonline.com/your-tenant-id-here

AZURE_CLIENT_SECRET=your-client-secret-here

OFFICE365_USER_EMAIL=your-email@yourdomain.com

```



⚠️ **NEVER commit the `.env` file to Git!**



---



## ☁️ Azure Configuration



### Step 1: Create Azure AD App Registration



1. Go to [Azure Portal](https://portal.azure.com)

2. Navigate to **Azure Active Directory** → **App registrations**

3. Click **+ New registration**

4. Configure:

   - **Name:** `Office 365 MCP Server` (or your preferred name)

   - **Supported account types:** `Accounts in this organizational directory only`

   - **Redirect URI:** Leave blank

5. Click **Register**



### Step 2: Note Your Credentials



After registration, note these values:

- **Application (client) ID** - Use for `AZURE_CLIENT_ID`

- **Directory (tenant) ID** - Use in `AZURE_AUTHORITY` URL



### Step 3: Create Client Secret



1. In your app registration, go to **Certificates & secrets**

2. Click **+ New client secret**

3. Add description: `MCP Server Secret`

4. Set expiry: `90 days` (recommended, or choose your preference)

5. Click **Add**

6. **⚠️ IMPORTANT:** Copy the **Value** immediately (shown only once!)

7. Use this for `AZURE_CLIENT_SECRET`



### Step 4: Configure API Permissions



1. In your app registration, go to **API permissions**

2. Click **+ Add a permission** → **Microsoft Graph** → **Application permissions**

3. Add these permissions:



   **Required Permissions (Minimum - 4 tools):**

   - `User.Read.All`

   - `Mail.Read`

   - `Calendars.Read`

   - `Files.Read.All`



   **Full Feature Set (All 45 tools):**

   - `Mail.ReadWrite` - Email management

   - `Mail.Send` - Send emails

   - `MailboxSettings.ReadWrite` - Mailbox configuration

   - `Calendars.ReadWrite` - Calendar operations

   - `Files.ReadWrite.All` - File management

   - `Contacts.ReadWrite` - Contact management

   - `Team.ReadBasic.All` - Teams access

   - `Channel.ReadBasic.All` - Channel information

   - `ChannelMessage.Send` - Send channel messages

   - `ChannelMessage.Read.All` - Read channel messages

   - `Chat.ReadWrite` - Chat management

   - `Tasks.ReadWrite` - Task management



4. Click **Add permissions**



### Step 5: Grant Admin Consent



**⚠️ CRITICAL:** After adding permissions:



1. Click **✓ Grant admin consent for [Your Organization]**

2. Click **Yes** to confirm

3. Wait for all permissions to show **✓ Granted** status



**Note:** Admin consent is required for Application permissions. Contact your Microsoft 365 administrator if you don't have sufficient privileges.



For detailed instructions, see [AZURE_PERMISSIONS_SETUP.md](AZURE_PERMISSIONS_SETUP.md).



---



## 🤖 Claude Code CLI Setup



### Configuration



Add this MCP server to your Claude Code configuration:



**Location:** `~/.claude.json`



```json

{

  "mcpServers": {

    "office365": {

      "type": "stdio",

      "command": "node",

      "args": ["/absolute/path/to/office365-mcp-server/office365-sdk.js"],

      "env": {

        "AZURE_CLIENT_ID": "your-client-id-here",

        "AZURE_CLIENT_SECRET": "your-client-secret-here",

        "AZURE_AUTHORITY": "https://login.microsoftonline.com/your-tenant-id-here",

        "OFFICE365_USER_EMAIL": "your-email@yourdomain.com"

      }

    }

  }

}

```



**Important:**

- Replace `/absolute/path/to/office365-mcp-server/` with the actual path

- Use absolute paths, not relative paths

- Add your actual Azure credentials to the `env` section



### Verify Installation



1. Restart Claude Code CLI

2. In a new conversation, type:

   ```

   list office 365 tools

   ```

3. You should see 45 available tools



**Troubleshooting:** If tools don't appear, check:

- Path to `office365-sdk.js` is absolute and correct

- All environment variables are set in `~/.claude.json`

- Node.js 18+ is installed: `node --version`

- Dependencies are installed: `npm install`



---



## 🚀 Usage



Once configured in Claude Code CLI, you can use natural language to interact with Office 365:



### Example Commands



**Email:**

```

"Show me my last 10 emails"

"Search for emails from jeff@example.com about Q4 budget"

"Send an email to team@company.com with subject 'Meeting Notes'"

"What emails are in my Sent Items folder?"

```



**Calendar:**

```

"What's on my calendar this week?"

"Create a meeting tomorrow at 2pm for 1 hour"

"Show all events in the next 30 days"

```



**Files:**

```

"List files in my OneDrive root folder"

"Search for files containing 'proposal'"

"Show me PDF files modified this month"

```



**Contacts:**

```

"List all my contacts"

"Find contact information for John Smith"

```



**Teams:**

```

"List all my Teams"

"Show channels in the Marketing team"

"Get recent messages from the General channel"

```



**Tasks:**

```

"Show my task lists"

"What tasks are incomplete?"

"Create a task in my To-Do list"

```



---



## 📚 Available Tools



### 📧 Email Management (16 tools)



| Tool | Description |

|------|-------------|

| `get_recent_emails` | Get recent emails from inbox |

| `search_emails` | Search emails with query |

| `get_email_by_id` | Get specific email details |

| `send_email` | Send an email |

| `reply_to_email` | Reply to an email |

| `forward_email` | Forward an email |

| `list_mail_folders` | List all mail folders |

| `get_folder_emails` | Get emails from specific folder |

| `search_in_folder` | Search within specific folder |

| `move_email` | Move email to folder |

| `delete_email` | Delete an email |

| `mark_as_read` | Mark email as read |

| `mark_as_unread` | Mark email as unread |

| `get_email_attachments` | List email attachments |

| `download_attachment` | Download attachment |

| `create_mail_folder` | Create new folder |



### 📅 Calendar Operations (9 tools)



| Tool | Description |

|------|-------------|

| `get_calendar_events` | Get upcoming calendar events |

| `get_event_by_id` | Get specific event details |

| `create_calendar_event` | Create new calendar event |

| `update_calendar_event` | Update existing event |

| `delete_calendar_event` | Delete an event |

| `list_calendars` | List all calendars |

| `get_calendar_view` | Get events in date range |

| `find_meeting_times` | Find available meeting times |

| `accept_event` | Accept meeting invitation |



### 📁 OneDrive Files (8 tools)



| Tool | Description |

|------|-------------|

| `list_drive_items` | List files in folder |

| `get_file_by_id` | Get file details |

| `search_drive` | Search for files |

| `download_file` | Download file content |

| `upload_file` | Upload new file |

| `create_folder` | Create new folder |

| `delete_file` | Delete file or folder |

| `move_file` | Move file to folder |



### 👥 Contacts (4 tools)



| Tool | Description |

|------|-------------|

| `list_contacts` | List all contacts |

| `get_contact_by_id` | Get specific contact |

| `create_contact` | Create new contact |

| `search_contacts` | Search contacts |



### 💬 Microsoft Teams (5 tools)



| Tool | Description |

|------|-------------|

| `list_teams` | List all teams |

| `list_channels` | List channels in team |

| `get_channel_messages` | Get channel messages |

| `send_channel_message` | Send message to channel |

| `list_chats` | List recent chats |



### ✅ Tasks & To-Do (4 tools)



| Tool | Description |

|------|-------------|

| `list_todo_lists` | List all task lists |

| `get_list_tasks` | Get tasks from list |

| `create_task` | Create new task |

| `update_task` | Update existing task |



**For complete tool documentation, see [OFFICE365_TOOLS.md](OFFICE365_TOOLS.md)**



---



## 🧪 Testing



### Option 1: Test with Claude Code CLI



Simply use the natural language commands in Claude Code after setup.



### Option 2: Standalone Testing



Test the server independently:



```bash

# Test basic authentication

node tests/simple-test.js



# Test MCP server protocol

node tests/simple-mcp-server.js

```



**Note:** Standalone testing requires credentials in `.env` file.



---



## 🔐 Security



### Best Practices



✅ **Environment Variables:** All credentials stored in environment variables

✅ **No Hardcoded Secrets:** No credentials in source code

✅ **Git Protection:** `.gitignore` prevents credential commits

✅ **Validation:** Startup validation ensures all required variables are set

✅ **Admin Consent:** Application permissions require admin approval



### Security Features



- **Application Permissions:** Server-to-service authentication (no user prompts)

- **Scoped Access:** Limited to configured user account

- **Audit Logging:** Use Azure AD audit logs to monitor access

- **Secret Rotation:** Rotate client secrets every 90 days (recommended)



### Security Documentation



- [SECURITY.md](SECURITY.md) - Security policy and responsible disclosure

- [SECURITY_SCAN_REPORT.md](SECURITY_SCAN_REPORT.md) - Vulnerability analysis

- [FINAL_SECURITY_AUDIT.md](FINAL_SECURITY_AUDIT.md) - Pre-publication audit



**⚠️ Never commit `.env` files or expose credentials in code!**



---



## 🐛 Troubleshooting



### Tools Not Appearing in Claude Code



**Check:**

1. Path in `~/.claude.json` is absolute (not relative)

2. All environment variables are set in `~/.claude.json` `env` section

3. Claude Code CLI has been restarted after configuration

4. Run `node office365-sdk.js` - should start without errors



### Authentication Errors



**401 Unauthorized:**

- Verify `AZURE_CLIENT_SECRET` is correct (use Value, not Secret ID)

- Check secret hasn't expired in Azure Portal

- Ensure `AZURE_CLIENT_ID` and `AZURE_AUTHORITY` are correct



**403 Forbidden:**

- Admin consent not granted - check Azure Portal API permissions

- Wait 5-10 minutes after granting consent for propagation

- Verify permissions show "✓ Granted" status



### Missing Permissions



**Error:** "Insufficient privileges to complete the operation"



**Solution:**

1. Go to Azure Portal → App registrations → Your app

2. API permissions → Check all required permissions are added

3. Click "Grant admin consent" again

4. Verify all show "✓ Granted" status



### Connection Issues



**Server fails to start:**

- Check Node.js version: `node --version` (need 18+)

- Reinstall dependencies: `rm -rf node_modules && npm install`

- Verify all environment variables are set

- Check for typos in `~/.claude.json` (validate JSON syntax)



**For more troubleshooting, see [AZURE_PERMISSIONS_SETUP.md](AZURE_PERMISSIONS_SETUP.md#troubleshooting)**



---



## 🤝 Contributing



Contributions are welcome! This is an open-source project.



### How to Contribute



1. Fork the repository

2. Create a feature branch: `git checkout -b feature/amazing-feature`

3. Make your changes

4. Test thoroughly with Claude Code CLI

5. Commit your changes: `git commit -m 'Add amazing feature'`

6. Push to your fork: `git push origin feature/amazing-feature`

7. Open a Pull Request



### Development Guidelines



- Follow existing code style (2-space indentation for JavaScript)

- Add tests for new features

- Update documentation for new tools

- No hardcoded credentials in code

- Use environment variables for configuration



### Reporting Issues



Found a bug or have a suggestion? [Open an issue](https://github.com/eesb99/office365-mcp-server/issues)



**Include:**

- Claude Code CLI version

- Node.js version

- Operating system

- Error messages (remove any credentials!)

- Steps to reproduce



---



## 📄 License



This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.



```

MIT License



Copyright (c) 2025 eesb99



Permission is hereby granted, free of charge, to any person obtaining a copy

of this software and associated documentation files (the "Software"), to deal

in the Software without restriction, including without limitation the rights

to use, copy, modify, merge, publish, distribute, sublicense, and/or sell

copies of the Software, and to permit persons to whom the Software is

furnished to do so, subject to the following conditions:



The above copyright notice and this permission notice shall be included in all

copies or substantial portions of the Software.



THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR

IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,

FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE

AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER

LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,

OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE

SOFTWARE.

```



---



## 🙏 Acknowledgments



- Built with [Model Context Protocol (MCP) SDK](https://modelcontextprotocol.io)

- Powered by [Microsoft Graph API](https://developer.microsoft.com/graph)

- Designed for [Claude Code CLI](https://claude.com/claude-code)

- Created with assistance from [Claude Code](https://claude.com/claude-code)



---



## 📞 Support & Contact



- **GitHub:** [@eesb99](https://github.com/eesb99)

- **Email:** eesb99@gmail.com

- **Issues:** [GitHub Issues](https://github.com/eesb99/office365-mcp-server/issues)



---



## 📊 Project Stats



- **Version:** 2.0.0 (Security Hardened)

- **Total Tools:** 45

- **Code Quality:** Production Ready

- **Testing:** Tested with Claude Code CLI

- **Security Audit:** Passed (see [FINAL_SECURITY_AUDIT.md](FINAL_SECURITY_AUDIT.md))

- **Last Updated:** 2025-10-29



---



## 🌟 Star History



If you find this project useful, please consider giving it a star on GitHub! ⭐



---



**Made with ❤️ for the Claude Code community**