Office 365 MCP Server
A Model Context Protocol (MCP) server for Microsoft 365 integration. Provides 24 consolidated tools for email, calendar, Teams, planner, and notifications through the Microsoft Graph API.
Installation
npx office-365-mcp-serverAsk AI about Office 365 MCP Server
Powered by Claude Β· Grounded in docs
I know everything about Office 365 MCP Server. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Office MCP Server
This is a comprehensive implementation of the Office MCP (Model Context Protocol) server that connects Claude with Microsoft 365 services through the Microsoft Graph API.
Headless Operation! Run without browser authentication after initial setup. Automatic token refresh and Windows Task Scheduler support for invisible background operation. See TASK_SCHEDULER_SETUP.md for Windows setup guide.
DEVELOPMENT STATUS: This project is under active development and is not yet production-ready. APIs, interfaces, and functionality may change without notice. Use at your own risk for evaluation and testing purposes only. Not recommended for production deployments.
Features
- Complete Microsoft 365 Integration: Email, Calendar, Teams, OneDrive/SharePoint, Contacts, Planner, To Do, Groups, and Directory
- Consolidated Tool Architecture: Operation-based routing reduces tool count for efficient LLM context usage
- Headless Operation: Run without browser after initial authentication
- Automatic Token Management: Persistent token storage with automatic refresh
- Shared Mailbox Support: Access shared mailboxes with
.Sharedscopes - Centralized Error Handling: Consistent error formatting with actionable hints for Graph API errors
- Email Attachment Handling: Download embedded attachments and map SharePoint URLs to local paths
- Advanced Email Search: Unified search with KQL support and automatic query optimization
- Teams Meeting Management: Access transcripts, recordings, and AI insights
- File Management: Full OneDrive and SharePoint file operations with cross-drive support
- Contact Management: Full CRUD operations for Outlook contacts with advanced search
- Task Management: Microsoft Planner and To Do integration
- Configurable Paths: Environment variables for all local sync paths
Quick Start
Prerequisites
- Node.js 16 or higher
- Microsoft 365 account (personal or work/school)
- Azure App Registration (see below)
Installation
- Clone the repository:
git clone https://github.com/yourusername/office-mcp.git
cd office-mcp
- Install dependencies:
npm install
- Copy the environment template:
cp .env.example .env
-
Configure your
.envfile with:- Azure App credentials (see Azure Setup below)
- Local file paths for SharePoint/OneDrive sync
- Optional settings
-
Run initial authentication:
npm run auth-server
# Visit http://localhost:3000/auth and sign in
- Configure Claude Desktop (see Claude Desktop Configuration below)
Tool Architecture
The server uses a consolidated tool design where each Microsoft 365 domain is exposed as a single tool with operation (and optionally entity) routing. This minimizes LLM context overhead while providing full functionality.
| Tool | Domain | Operations |
|---|---|---|
system | Auth & server info | about, authenticate, check_status |
mail | list, read, send, reply, draft, search, move, folder, rules, categories, focused | |
calendar | Calendar events | list, get, create, update, delete, find_free_slots |
teams_meeting | Teams meetings | create, update, cancel, find, list_transcripts, get_transcript, get_recordings |
teams_channel | Teams channels | list, create, get, update, delete, send_message, list_messages, list_members |
teams_chat | Teams chat | list, create, get, send_message, list_messages, list_members |
files | OneDrive/SharePoint | list, get, search, upload, download, create_folder, delete, move, copy, share β all operations support cross-drive via driveId |
search | Unified search | Keyword-based search across mail, files, events β returns ID and DriveID for actionable results |
contacts | Outlook contacts | list, get, create, update, delete, search, list_folders |
planner | Microsoft Planner | Entity+operation: plan.list, task.create, bucket.get_tasks, user.lookup, etc. |
todo | Microsoft To Do | list_lists, create_list, list_tasks, create_task, update_task, list_checklist, etc. |
groups | M365 Groups | list, get, create, update, delete, list_members, add_member, remove_member, list_owners, get_drive, list_drives |
directory | User directory | lookup_user, get_profile, get_manager, get_reports, get_presence, search_users |
notifications | Webhooks | create, list, renew, delete |
Error Handling
All tools are wrapped with safeTool() which provides:
- Consistent
isError: trueresponses for failures - Context-tagged messages (e.g.,
[calendar.create] Error: ...) - Actionable hints for common Graph API errors (401, 403, 404, 429)
Azure App Registration & Configuration
To use this MCP server you need to first register and configure an app in Azure Portal. The following steps will take you through the process of registering a new app, configuring its permissions, and generating a client secret.
App Registration
- Open Azure Portal in your browser
- Sign in with a Microsoft Work or Personal account
- Search for or click on "App registrations"
- Click on "New registration"
- Enter a name for the app, for example "Office MCP Server"
- Select the "Accounts in any organizational directory and personal Microsoft accounts" option
- In the "Redirect URI" section, select "Web" from the dropdown and enter "http://localhost:3000/auth/callback" in the textbox
- Click on "Register"
- From the Overview section of the app settings page, copy the "Application (client) ID" and enter it as the OFFICE_CLIENT_ID in the .env file as well as in the claude-config-sample.json file
App Permissions
- From the app settings page in Azure Portal select the "API permissions" option under the Manage section
- Click on "Add a permission"
- Click on "Microsoft Graph"
- Select "Delegated permissions"
- Search for and select the checkbox next to each of these permissions:
- offline_access
- User.Read
- User.ReadWrite
- User.ReadBasic.All
- Mail.ReadWrite
- Mail.Send
- Mail.ReadWrite.Shared
- Mail.Send.Shared
- MailboxSettings.ReadWrite
- Calendars.ReadWrite
- Contacts.ReadWrite
- Files.ReadWrite.All
- Team.ReadBasic.All
- Team.Create
- Chat.ReadWrite
- ChannelMessage.Read.All
- ChannelMessage.Send
- OnlineMeetingTranscript.Read.All
- OnlineMeetings.ReadWrite
- Tasks.ReadWrite
- Group.Read.All
- Directory.Read.All
- Presence.ReadWrite
- Sites.Read.All
- Click on "Add permissions"
Client Secret
- From the app settings page in Azure Portal select the "Certificates & secrets" option under the Manage section
- Switch to the "Client secrets" tab
- Click on "New client secret"
- Enter a description, for example "Client Secret"
- Select the longest possible expiration time
- Click on "Add"
- Copy the secret value and enter it as the OFFICE_CLIENT_SECRET in the .env file as well as in the claude-config-sample.json file
Environment Configuration
Required Variables
# Azure App Registration
OFFICE_CLIENT_ID=your-azure-app-client-id
OFFICE_CLIENT_SECRET=your-azure-app-client-secret
OFFICE_TENANT_ID=common
# Authentication
OFFICE_REDIRECT_URI=http://localhost:3000/auth/callback
Optional Variables
# Local file paths (customize to your system)
SHAREPOINT_SYNC_PATH=/path/to/your/sharepoint/sync
ONEDRIVE_SYNC_PATH=/path/to/your/onedrive/sync
TEMP_ATTACHMENTS_PATH=/path/to/temp/attachments
SHAREPOINT_SYMLINK_PATH=/path/to/sharepoint/symlink
# Server settings
USE_TEST_MODE=false
TRANSPORT_TYPE=stdio # or 'http' for SSE headless mode
HTTP_PORT=3333
HTTP_HOST=127.0.0.1
Claude Desktop Configuration
-
Locate your Claude Desktop configuration file:
- Windows:
%APPDATA%\Claude\claude_desktop_config.json - macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
- Windows:
-
Add the MCP server configuration:
{
"mcpServers": {
"office-mcp": {
"command": "node",
"args": ["/path/to/office-mcp/index.js"],
"env": {
"OFFICE_CLIENT_ID": "your-client-id",
"OFFICE_CLIENT_SECRET": "your-client-secret",
"SHAREPOINT_SYNC_PATH": "/path/to/sharepoint",
"ONEDRIVE_SYNC_PATH": "/path/to/onedrive"
}
}
}
}
-
Restart Claude Desktop
-
In Claude, use the
systemtool withoperation: "authenticate"to connect to Microsoft 365
Testing
MCP Inspector
Test the server directly using the MCP Inspector:
npx @modelcontextprotocol/inspector node index.js
Test Mode
Enable test mode to use mock data without API calls:
USE_TEST_MODE=true node index.js
Unit Tests
npm test
Authentication Flow
- Start the authentication server:
- Run
./start-auth-server.sh(or usenpm run auth-server)
- Run
- The auth server runs on port 3000 and handles OAuth callbacks
- In Claude, use the
systemtool withoperation: "authenticate"to get an authentication URL - Complete the authentication in your browser
- Tokens are stored in
~/.office-mcp-tokens.json
Headless Operation
Automatic Token Refresh
After initial authentication, the server automatically refreshes tokens without user interaction.
HTTP/SSE Transport Mode
For headless environments, use SSE transport:
TRANSPORT_TYPE=http HTTP_PORT=3333 node index.js
The server exposes /sse (GET) for SSE connections and /message (POST) for client messages.
Windows Service (Optional)
For Windows background operation:
- Complete initial authentication
- Configure as Windows Task Scheduler task
- Runs invisibly at system startup
Troubleshooting
Common Issues
-
Authentication Errors
- Ensure Azure App has correct permissions
- Check token file exists:
~/.office-mcp-tokens.json - Verify redirect URI matches Azure configuration
-
Email Search with Date Filters
- Date-filtered searches now route directly to $filter API for reliability
- Use wildcard
*for all emails in a date range - Both
startDateandendDatesupport ISO format (2025-08-27) or relative (7d/1w/1m/1y)
-
Email Attachment Issues
- Configure local sync paths in
.env - Ensure temp directory has write permissions
- Check SharePoint sync is active
- Configure local sync paths in
-
API Rate Limits
- Server includes automatic retry with exponential backoff
- Reduce request frequency if persistent
-
Permission Errors
- Verify all required Graph API permissions are granted
- Admin consent may be required for some permissions
Security Considerations
- Secure Token Storage: Tokens are stored with restricted file permissions (0o600) using atomic writes to prevent corruption
- No Credential Logging: Token content is never logged; only boolean presence checks are used
- Sensitive Data Redaction: Email bodies, recipients, and search queries are not logged; API URLs with query params are gated behind DEBUG_VERBOSE
- Environment Variables: Never commit
.envfiles - Client Secrets: Rotate regularly and use Azure Key Vault in production
- Local Paths: Use environment variables instead of hardcoding paths
- Graceful Shutdown: Proper SIGTERM/SIGINT handling for clean process termination
Contributing
Contributions are welcome! Please:
- Fork the repository
- Create a feature branch
- Submit a pull request
License
MIT License - See LICENSE file for details
