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

---

🧪 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: eesb99@gmail.com
• 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