SecchiAle/ms365-selective-mcp-server

Selective Microsoft 365 MCP Server

A streamable HTTPS Model Context Protocol (MCP) server designed specifically for Microsoft Planner, Teams, SharePoint, Outlook, and OneNote integration with Microsoft Copilot Studio and Azure App Service deployment.

🚀 Features

• Selective Service Focus: Only includes tools for the 5 core Microsoft 365 services
• Streamable HTTPS Transport: Compatible with Microsoft Copilot Studio and modern MCP clients
• Azure App Service Ready: Optimized for cloud deployment with proper configuration
• OAuth Integration: Full OAuth flow support for Copilot Studio connector integration
• 52 Focused Tools: Carefully curated from the original 99 tools for targeted functionality

📦 Supported Services & Tools

🗂️ Microsoft Planner (7 tools)

• list-planner-tasks - List user's planner tasks
• get-planner-plan - Get details of a specific plan
• list-plan-tasks - List tasks in a specific plan
• get-planner-task - Get details of a specific task
• create-planner-task - Create a new planner task
• update-planner-task - Update an existing task
• update-planner-task-details - Update task details

👥 Microsoft Teams (8 tools)

• list-joined-teams - List teams the user has joined
• get-team - Get details of a specific team
• list-team-channels - List channels in a team
• get-team-channel - Get details of a specific channel
• list-channel-messages - List messages in a channel
• get-channel-message - Get a specific channel message
• send-channel-message - Send a message to a channel
• list-team-members - List members of a team

📚 SharePoint Online (12 tools)

• search-sharepoint-sites - Search for SharePoint sites
• get-sharepoint-site - Get details of a specific site
• list-sharepoint-site-drives - List drives in a site
• get-sharepoint-site-drive-by-id - Get a specific drive
• list-sharepoint-site-items - List items in a site
• get-sharepoint-site-item - Get a specific item
• list-sharepoint-site-lists - List SharePoint lists
• get-sharepoint-site-list - Get details of a specific list
• list-sharepoint-site-list-items - List items in a SharePoint list
• get-sharepoint-site-list-item - Get a specific list item
• get-sharepoint-site-by-path - Get site by path
• get-sharepoint-sites-delta - Get site changes

📧 Outlook/Mail (16 tools)

• list-mail-messages - List mail messages
• list-mail-folders - List mail folders
• list-mail-folder-messages - List messages in a folder
• get-mail-message - Get a specific message
• send-mail - Send an email
• create-draft-email - Create a draft email
• delete-mail-message - Delete a message
• move-mail-message - Move a message
• add-mail-attachment - Add attachment to message
• list-mail-attachments - List message attachments
• get-mail-attachment - Get a specific attachment
• delete-mail-attachment - Delete an attachment
• list-outlook-contacts - List contacts
• get-outlook-contact - Get a specific contact
• create-outlook-contact - Create a new contact
• update-outlook-contact - Update a contact
• delete-outlook-contact - Delete a contact
• Plus shared mailbox tools for organization accounts

📝 OneNote (5 tools)

• list-onenote-notebooks - List OneNote notebooks
• list-onenote-notebook-sections - List sections in a notebook
• list-onenote-section-pages - List pages in a section
• get-onenote-page-content - Get page content
• create-onenote-page - Create a new page

🛠️ Prerequisites

• Node.js 18+ (recommended 20+)
• Azure AD App Registration for authentication
• Azure Subscription (for deployment)

⚡ Quick Start

1. Clone and Install

cd C:\AI_Projects\ms365-selective-mcp-server
npm install

2. Configure Environment

# Copy the example environment file
copy .env.example .env

# Edit .env and add your Azure AD app details:
# MS365_MCP_CLIENT_ID=your-app-id
# MS365_MCP_CLIENT_SECRET=your-app-secret

3. Build and Run Locally

# Build the project
npm run build

# Run with HTTP transport (for testing)
npm run start:http

# Or run with Azure configuration
npm run start:azure

4. Test the Server

# Check health endpoint
curl http://localhost:3000/health

# View service info
curl http://localhost:3000/

🌐 Deployment Options

Option 1: Azure App Service (Recommended)

1. Create Azure App Service:

   az webapp create --resource-group myRG --plan myPlan --name ms365-mcp --runtime "NODE|20-lts"
   

2. Configure Environment Variables in Azure Portal:

   • MS365_MCP_CLIENT_ID
   • MS365_MCP_CLIENT_SECRET
   • MS365_MCP_TENANT_ID
   • NODE_ENV=production

3. Deploy:

   • Via GitHub Actions (recommended)
   • Via Azure CLI: az webapp deployment source config-zip
   • Via VS Code Azure extension

Option 2: Docker Container

1. Build Image:

   docker build -t ms365-selective-mcp .
   

2. Run Container:

   docker run -p 3000:3000 \
     -e MS365_MCP_CLIENT_ID=your-id \
     -e MS365_MCP_CLIENT_SECRET=your-secret \
     ms365-selective-mcp
   

🔗 Microsoft Copilot Studio Integration

1. Set Up Azure AD App Registration

1. Go to Azure Portal → Azure Active Directory → App registrations
2. Create new registration: "MS365 Selective MCP Server"
3. Add redirect URIs:
   • https://your-app-service.azurewebsites.net/auth/callback
   • For local testing: http://localhost:3000/auth/callback
4. Generate client secret
5. Configure API permissions for Microsoft Graph

2. Create Custom Connector in Power Platform

1. Go to make.powerapps.com → Custom connectors
2. Create from blank
3. Set Host to your Azure App Service URL
4. Configure OAuth 2.0 authentication:
   • Authorization URL: https://your-app.azurewebsites.net/auth/authorize
   • Token URL: https://your-app.azurewebsites.net/auth/token
   • Client ID: Your Azure AD app client ID

3. Add to Copilot Studio Agent

1. Go to Copilot Studio
2. Create/edit your agent
3. Go to Tools → Add tool
4. Select "Model Context Protocol" tab
5. Choose your custom connector
6. Create connection and add to agent

🔧 Configuration Options

Environment Variables

Command Line Options

# HTTP mode with specific port
npm run start:http

# Azure mode (binds to 0.0.0.0:$PORT)
npm run start:azure

# Development mode with auto-reload
npm run dev:http

# Enable verbose logging
node dist/index.js --http 3000 -v

# Filter specific tools only
node dist/index.js --http 3000 --enabled-tools "planner|teams"

# Read-only mode
node dist/index.js --http 3000 --read-only

🧪 Testing

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Lint code
npm run lint

# Format code
npm run format

# Verify everything
npm run verify

📚 API Endpoints

Core Endpoints

• POST /mcp - Main MCP protocol endpoint
• GET /health - Health check
• GET / - Service information

OAuth Endpoints (Copilot Studio Integration)

• GET /.well-known/oauth_server - OAuth discovery
• GET /auth/authorize - OAuth authorization
• POST /auth/token - OAuth token exchange
• GET /auth/callback - OAuth callback

🔐 Security Features

• JWT Token Validation for OAuth requests
• CORS Configuration for cross-origin requests
• Rate Limiting on authentication endpoints
• Secure Token Storage with keychain fallback
• Environment Variable Security for secrets
• Request Logging for audit trails

📊 Monitoring

Health Check Response

{
  "status": "healthy",
  "service": "Selective Microsoft 365 MCP Server",
  "version": "1.0.0",
  "timestamp": "2025-01-XX:XX:XX.XXXZ"
}

Logs

• Console Logs: Development environment
• File Logs: error.log, combined.log
• Structured JSON: Production environment
• Azure App Service: Integrated with Azure Monitor

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make changes and test: npm run verify
4. Commit changes: git commit -am 'Add feature'
5. Push to branch: git push origin feature-name
6. Create Pull Request

📄 License

MIT License - see LICENSE file for details.

🆘 Support

• Issues: Create an issue in the repository
• Documentation: Check this README and code comments
• Azure Support: Use Azure support channels for deployment issues
• Microsoft Graph: Use Microsoft Graph documentation for API questions

Built for Microsoft Copilot Studio integration 🤖 Optimized for Azure deployment ☁️