office-365-mcp-server by hvkshetry - MCP Server

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.

Full Tool Documentation

For detailed documentation of all available tools and usage examples, see

Directory Structure

/office-mcp/
├── index.js                 # Main entry point
├── config.js                # Configuration settings
├── auth/                    # Authentication modules
│   ├── index.js             # Authentication exports
│   ├── token-manager.js     # Token storage and refresh
│   └── tools.js             # Auth-related tools
├── calendar/                # Calendar functionality
│   ├── index.js             # Calendar exports
│   ├── list.js              # List events
│   ├── create.js            # Create event
│   ├── update.js            # Update event
│   └── ...                  # Other calendar operations
├── email/                   # Email functionality
│   ├── index.js             # Email exports
│   ├── list.js              # List emails
│   ├── search.js            # Search emails
│   ├── read.js              # Read email
│   └── send.js              # Send email
├── folder/                  # Email folder functionality
│   ├── index.js             # Folder exports
│   ├── list.js              # List folders
│   ├── create.js            # Create folder
│   └── ...                  # Other folder operations
├── teams/                   # Teams functionality
│   ├── index.js             # Teams exports
│   ├── list.js              # List teams
│   ├── channels.js          # Channel operations
│   ├── messages.js          # Message operations
│   └── ...                  # Other Teams operations
├── planner/                 # Planner functionality
│   ├── index.js             # Planner exports
│   ├── plans.js             # Plan operations
│   ├── tasks.js             # Task operations
│   └── ...                  # Other Planner operations
├── notifications/           # Notification functionality
│   ├── index.js             # Notification exports
│   └── subscriptions.js     # Webhook subscriptions
├── utils/                   # Utility functions
│   ├── graph-api.js         # Microsoft Graph API helper
│   └── mock-data.js         # Test mode mock data
├── office-auth-server.js    # OAuth2 authentication server
├── config.js                # Configuration settings
├── package.json             # Dependencies
└── README.md                # This file

Features

Email Operations: List, search, read, send, and manage emails and folders
Calendar Management: Create, update, delete, and search calendar events
Teams Integration: Access teams, channels, messages, and meeting transcripts
Planner Support: Manage plans, tasks, buckets, and assignments
Notifications: Set up webhook subscriptions for real-time updates
Authentication: Secure OAuth2 flow with token management
Test Mode: Built-in mock data for development and testing

Prerequisites

Node.js: Version 16.x or higher
Azure App Registration: Required for Microsoft Graph API access
npm: For dependency management

Setup

1. Register an Azure Application

Go to the Azure Portal
Navigate to "Azure Active Directory" → "App registrations"
Click "New registration"
Configure your app:
- Name: "Office MCP Server" (or your preferred name)
- Supported account types: Choose based on your needs:
  - "Single tenant" for organization-only access
  - "Multitenant" for broader access
  - "Multitenant + Personal Microsoft accounts" for maximum compatibility
- Redirect URI: Set to http://localhost:3333/auth/callback (Web platform)

2. Configure API Permissions

After registration, configure the following permissions:

Go to "API permissions" in your app registration
Click "Add a permission" → "Microsoft Graph" → "Delegated permissions"
Add these permissions:
- Email: Mail.Read, Mail.ReadWrite, Mail.Send, MailboxSettings.ReadWrite
- Calendar: Calendars.Read, Calendars.ReadWrite
- Files: Files.Read, Files.ReadWrite
- Teams: Team.ReadBasic.All, Team.Create, Chat.Read, Chat.ReadWrite, ChannelMessage.Read.All, ChannelMessage.Send
- Meetings: OnlineMeetings.ReadWrite, OnlineMeetingTranscript.Read.All
- Planner: Tasks.Read, Tasks.ReadWrite
- User: User.Read, User.ReadWrite

3. Create Client Secret

Go to "Certificates & secrets"
Click "New client secret"
Add a description and choose expiry period
Copy the secret value immediately (it won't be shown again)

4. Install and Configure

# Clone the repository
git clone https://github.com/hvkshetry/office-365-mcp-server.git
cd office-mcp-server

# Install dependencies
npm install

# Copy environment template
cp .env.example .env

# Edit .env with your Azure app details:
# - OFFICE_CLIENT_ID: Your Application (client) ID
# - OFFICE_CLIENT_SECRET: Your client secret value

5. Start the Servers

Both the authentication server and the MCP server must be running before you can use any Office MCP tools. On Windows you can start them together using the included batch file:

# Windows – launch both servers
run-office-mcp.bat

# Or start them individually
start-auth-server.bat   # authentication server
npm start               # MCP server

# macOS/Linux
./start-auth-server.sh
npm start

6. Configure Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "office-mcp": {
      "command": "node",
      "args": ["path/to/office-mcp-server/index.js"],
      "env": {
        "OFFICE_CLIENT_ID": "your-client-id",
        "OFFICE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Authentication Flow

Ensure both the authentication server (runs on port 3333) and the MCP server are running
Use the authenticate tool in Claude to initiate OAuth2 flow
A browser window opens for Microsoft login
After successful login, tokens are stored locally
Tokens auto-refresh when needed

Testing

Enable test mode to use mock data without Microsoft 365 connection:

# Set in .env or environment
USE_TEST_MODE=true

Run tests:

npm test

Troubleshooting

Authentication Issues

"Application not found": Ensure client ID is correct
"Invalid client secret": Check secret hasn't expired
"Redirect URI mismatch": Verify http://localhost:3333/auth/callback is configured in Azure

Permission Errors

"Insufficient privileges": Add required permissions in Azure portal
"Consent required": Admin consent may be needed for some permissions

Token Issues

"Token expired": Tokens should auto-refresh; try re-authenticating
"Invalid token": Delete ~/.office-mcp-tokens.json and re-authenticate

Security Notes

Store credentials securely in environment variables
Never commit .env files to version control
Tokens are stored locally in ~/.office-mcp-tokens.json
Use appropriate Azure AD permissions for your use case

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Add tests for new functionality
Submit a pull request

License

MIT License - see LICENSE file for details