Office 365 MCP Server

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

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
• Installation
• Azure Configuration
• Claude Code CLI Setup
• Usage
• Available Tools
• Testing
• Security
• Troubleshooting
• Contributing
• 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

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

2. Install Dependencies

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:

cp .env.example .env

Edit .env with your Azure credentials (see Azure Configuration below):

AZURE_CLIENT_ID=your-client-id-here
AZURE_AUTHORITY=https://login.microsoftonline.com/your-tenant-id-here
AZURE_CLIENT_SECRET=your-client-secret-here
[email protected]

⚠️ NEVER commit the .env file to Git!

☁️ Azure Configuration

Step 1: Create Azure AD App Registration

1. Go to Azure Portal
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.

🤖 Claude Code CLI Setup

Configuration

Add this MCP server to your Claude Code configuration:

Location: ~/.claude.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": "[email protected]"
      }
    }
  }
}

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 [email protected] about Q4 budget"
"Send an email to [email protected] 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

🧪 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:

# 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 policy and responsible disclosure
• SECURITY_SCAN_REPORT.md - Vulnerability analysis
• 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

🤝 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

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 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
• Powered by Microsoft Graph API
• Designed for Claude Code CLI
• Created with assistance from Claude Code

📞 Support & Contact

• GitHub: @eesb99
• Email: [email protected]
• Issues: GitHub 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)
• 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