What is Mcp Microsoft Office

MCP-Microsoft-Office is a local MCP server that acts as a bridge between Microsoft Graph API and MCP-compatible LLMs, allowing seamless interaction with Microsoft 365 data such as emails, calendar events, files, and contacts through natural language.

Use cases

Use cases include automating email management, scheduling calendar events, retrieving contact information, and enhancing productivity tools by enabling natural language queries to interact with Microsoft 365 data.

How to use

To use MCP-Microsoft-Office, set up the server in your environment, authenticate using OAuth 2.0, and utilize the provided tools to interact with your Microsoft 365 data through LLMs like Claude.

Key features

Key features include a complete implementation of the Model Context Protocol, integration with Microsoft Graph API, production-ready tools for email and calendar management, enterprise-grade architecture with proper authentication, error handling, and logging.

Where to use

MCP-Microsoft-Office can be used in various fields such as enterprise environments, software development, and any application requiring integration with Microsoft 365 services and natural language processing.

MCP Microsoft Office Bridge

A production-ready bridge connecting LLMs to Microsoft 365 via the Model Context Protocol (MCP)

This project is a comprehensive MCP server that enables Claude (and other LLM clients) to seamlessly interact with your Microsoft 365 data - emails, calendar events, files, and contacts - through natural language. Built as a Windsurf Vibe Code project, it demonstrates enterprise-grade architecture with proper authentication, error handling, and modular design.

What This Is

Simply put: We are a bridge between Microsoft Graph API and MCP-compatible LLMs, handling authentication, data normalization, and tool orchestration so Claude can work with your Microsoft 365 data as naturally as it works with text.

The Problem We Solve

• LLMs can’t directly access Microsoft 365 - they need a bridge
• Microsoft Graph API is complex - requires OAuth, token management, data normalization
• MCP needs proper tool definitions - parameters, validation, error handling
• Enterprise needs reliability - proper logging, caching, error recovery

Our Solution

• Complete MCP Server - Full Model Context Protocol implementation
• Microsoft Graph Integration - OAuth 2.0, token refresh, API calls
• Production-Ready Tools - 25+ working tools with proper validation
• Enterprise Architecture - Modular, async, error-handled, logged
• Desktop & Web - Electron app + web interface

What We’ve Built

Core Architecture

Claude/LLM ←→ MCP Adapter ←→ Express API ←→ Graph Services ←→ Microsoft 365

Production-Ready Tools

Mail Tools (80% Working)

• getMail - Read emails from inbox
• sendMail - Send emails with attachments
• searchMail - Search emails by query
• flagMail - Flag/unflag emails
• addMailAttachment - Add attachments to emails
• removeMailAttachment - Remove email attachments

Calendar Tools (100% Working)

• getCalendar - View calendar events
• createEvent - Create new events
• updateEvent - Modify existing events
• deleteEvent - Cancel events
• acceptEvent - Accept meeting invitations
• declineEvent - Decline meeting invitations
• tentativelyAcceptEvent - Tentatively accept invitations
• addAttachment - Add files to calendar events
• removeAttachment - Remove event attachments
• getAvailability - Check free/busy times
• findMeetingTimes - Find optimal meeting slots
• scheduleMeeting - Smart meeting scheduling

Files Tools (70% Working)

• listFiles - Browse OneDrive/SharePoint
• uploadFile - Upload files to cloud storage
• downloadFile - Download file content
• getFileMetadata - Get file information
• shareFile - Share files with permissions

People Tools (100% Working)

• findPeople - Find contacts by name/email
• searchPeople - Search organization directory
• getRelevantPeople - Get frequently contacted people

AI Tools (100% Working)

• query - Natural language queries across all Microsoft 365 data

What We Fixed & Learned

Tool Definition Architecture

• Pattern Discovered: Every MCP tool needs proper parameter definitions with required: true
• Endpoint Consistency: Tool definitions must exactly match MCP adapter paths
• Parameter Mapping: inPath: true for URL parameters, proper validation schemas

Enterprise-Grade Error Handling

• Centralized Error Service: Consistent error creation across all modules
• Proper Async Patterns: All operations use async/await with Promise handling
• Input Validation: Joi schemas for all API endpoints
• Graceful Degradation: Cache fallbacks, token refresh, retry logic

Getting Started

Prerequisites

• Node.js 18+
• Microsoft 365 account
• Azure App Registration (free)

Quick Setup

1. Clone & Install

   git clone https://github.com/Aanerud/MCP-Microsoft-Office.git
   cd MCP-Microsoft-Office
   npm install
   

2. Azure App Registration

   • Go to Azure Portal
   • Create new app registration
   • Set redirect URI: http://localhost:3000/api/auth/callback
   • Grant permissions: User.Read, Mail.Read, Mail.Send, Calendars.ReadWrite, Files.Read, People.Read

3. Environment Setup

   # Create .env file
      MICROSOFT_CLIENT_ID=your_client_id
      MICROSOFT_TENANT_ID=your_tenant_id
      LLM_PROVIDER=claude  # or openai
      CLAUDE_API_KEY=your_claude_api_key
      OPENAI_API_KEY=your_openai_api_key
   

4. Start the Server

   # Development mode (full logging)
   npm run dev
   
   # Production mode (minimal logging)
   npm start
   
   

5. Authenticate

   • Open http://localhost:3000
   • Click “Login with Microsoft”
   • Complete OAuth flow

Claude Integration

1. Configure Claude Desktop
   Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

   {
     "mcpServers": {
       "microsoft365": {
         "command": "node",
         "args": [
           "/absolute/path/to/mcp-adapter.cjs"
         ],
         "restrictions": {}
       }
     }
   }
   

2. Start Using

   • Ensure MCP server is running (npm run dev)
   • Open Claude Desktop
   • Ask: “Show me my calendar for today”
   • Ask: “Send an email to [email protected] about the meeting”
   • Ask: “What files did I modify this week?”

Architecture Deep Dive

Modular Design

src/
├── api/                  # Express controllers & routes
├── auth/                 # Microsoft OAuth & MSAL
├── core/                 # Error handling, logging, tools
├── graph/                # Microsoft Graph API services
├── modules/              # Business logic (mail, calendar, files, people)
├── main/                 # Electron main process
└── renderer/             # Electron UI

Key Design Principles

• Async Everything: No blocking operations, proper Promise handling
• Error Boundaries: Centralized error service with categorization
• Data Normalization: Consistent response formats across all Graph data
• Modular Capabilities: Each module registers its own tools and handles intents
• Memory Safety: Circular logging buffers, garbage collection monitoring
• Development Transparency: Full logging in dev mode, minimal in production

MCP Adapter Flow

1. Claude Tool Call → JSON-RPC to MCP adapter
2. Parameter Validation → Tool definitions enforce required parameters
3. HTTP Request → Adapter calls Express API endpoints
4. Business Logic → Controllers invoke functional modules
5. Graph API Call → Services handle Microsoft Graph integration
6. Data Normalization → Consistent response formatting
7. Response → JSON-RPC back to Claude

Production Readiness

What’s Production Ready

• Complete MCP Server - Full Model Context Protocol implementation
• Microsoft Graph Integration - OAuth 2.0, token refresh, API calls
• Production-Ready Tools - 25+ working tools with proper validation
• Enterprise Architecture - Modular, async, error-handled, logged
• Desktop App - Electron with system tray integration
• Web Interface - Full browser-based experience

Enterprise Features

• Memory Management: Circular buffers prevent memory leaks
• Error Recovery: Automatic token refresh, retry logic
• Monitoring: Real-time memory usage, error throttling
• Caching: Intelligent caching with TTL for performance
• Security: Secure token storage, proper OAuth flows

What’s Next

This is a complete, working MCP server ready for production use. Future enhancements could include:

• Teams Integration: Chat, channels, meetings
• SharePoint Advanced: Sites, lists, workflows
• Power Platform: Power BI, Power Automate integration
• Advanced AI: Semantic search, content analysis
• Multi-Tenant: Support for multiple Microsoft 365 tenants

Contributing

This project demonstrates enterprise-grade MCP development. Key patterns to follow:

1. Tool Definitions: Always define proper parameter schemas
2. Async Patterns: Use async/await with proper error handling
3. Error Service: Use centralized error creation and logging
4. Data Normalization: Consistent response formats
5. Testing: Real API integration tests

License

MIT License - Build amazing things with Microsoft 365 and MCP!

Built with as a Windsurf Vibe Code project - demonstrating how to build production-ready MCP servers that bridge LLMs with enterprise APIs.