nickels/office365-mcp-server
3.1
If you are the rightful owner of office365-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
A containerized MS-365 Model Context Protocol (MCP) server with OpenTelemetry instrumentation for secure access and detailed telemetry data.
MS-365 MCP Server with OpenTelemetry Instrumentation
A containerized MS-365 Model Context Protocol (MCP) server with comprehensive OpenTelemetry instrumentation for monitoring and observability. This setup allows Claude Desktop to securely access Microsoft 365 services while providing detailed telemetry data for all operations.
Features
- š Secure MS-365 Integration: OAuth-based authentication with Microsoft 365 services
- š Full OpenTelemetry Instrumentation: Comprehensive monitoring of all MCP operations
- š³ Containerized Deployment: Easy deployment with Docker Compose
- š§ SSH-based MCP Connection: Secure connection from Claude Desktop via SSH
- š Rich Telemetry Data: Traces, metrics, and structured logs for all operations
- š”ļø Security Focused: Credential isolation and secure token storage
Architecture
āāāāāāāāāāāāāāāāāāā SSH (Port 2222) āāāāāāāāāāāāāāāāāāāāāāāāāāā
ā Claude Desktop āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā Docker Container ā
ā (macOS) ā ā āāāāāāāāāāāāāāāāāāāāā ā
āāāāāāāāāāāāāāāāāāā ā ā MCP Container ā ā
ā ā āāāāāāāāāāāāāāā ā ā
ā ā ā MCP Server ā ā ā
ā ā ā(Instrumented)ā ā ā
ā ā āāāāāāāā¬āāāāāāā ā ā
ā ā ā ā ā
ā ā OpenTelemetry ā ā
ā ā ā ā ā
ā āāāāāāāāāāā¼āāāāāāāāāā ā
āāāāāāāāāāāāāā¼āāāāāāāāāāāā
ā
OTLP Export
ā
ā¼
External OTEL Collector
(Your monitoring stack)
Quick Start
Prerequisites
- Docker and Docker Compose installed
- macOS with Claude Desktop app
sshpassinstalled:brew install hudochenkov/sshpass/sshpass- Access to an OpenTelemetry collector (optional but recommended)
1. Clone and Configure
git clone <your-repo>
cd office365-mcp-server
# Edit environment variables
cp .env.example .env
vim .env
2. Configuration
Update .env file:
# MS-365 Configuration
MCP_SSH_PASSWORD=YourSecurePassword123!
# OpenTelemetry Configuration (optional)
OTEL_EXPORTER_OTLP_ENDPOINT=http://your-otel-collector:4318
TELEMETRY_ENABLED=true
TELEMETRY_SAMPLE_RATE=1.0
TELEMETRY_LOG_OPERATIONS=true
OTEL_LOG_LEVEL=info
# Service identification
HOSTNAME=your-hostname
3. Deploy Container
# Build and start the container
docker-compose up -d
# Check container status
docker-compose logs -f ms365-mcp
4. Configure Claude Desktop
The setup automatically configures your Claude Desktop. Verify the configuration in:
~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"ms365": {
"command": "sshpass",
"args": [
"-p", "YourSecurePassword123!",
"ssh",
"-p", "2222",
"-o", "StrictHostKeyChecking=no",
"-o", "UserKnownHostsFile=/dev/null",
"mcp@localhost",
"/usr/local/bin/mcp-wrapper.sh"
],
"env": {}
}
}
}
5. First Connection
- Restart Claude Desktop to pick up the configuration
- Start a new conversation in Claude Desktop
- First-time setup: The MCP server will prompt for MS-365 authentication:
Please authenticate with Microsoft 365 by visiting: https://login.microsoftonline.com/... - Complete OAuth flow in your browser
- Credentials are cached for future use
Available MS-365 Operations
Once connected, you can ask Claude Desktop to:
š§ Email & Communication
- Read, send, and manage emails
- Access calendar events and scheduling
- Manage contacts and address books
š File Operations
- Access OneDrive files and folders
- Work with Excel, Word, PowerPoint documents
- Upload, download, and manage files
š Productivity Apps
- Manage Microsoft To-Do lists and tasks
- Access OneNote notebooks and notes
- Work with Microsoft Planner projects
š„ Collaboration
- Access Microsoft Teams data
- Manage SharePoint sites and content
- Work with shared workspaces
Monitoring and Observability
What Gets Monitored
Traces
- Every MCP operation with full context
- Operation duration and status
- Error details and stack traces
- User context and operation arguments
Metrics
mcp.operations.total- Counter of operations by type/categorymcp.operation.duration- Histogram of operation durationsmcp.errors.total- Counter of errors by type
Logs
- Structured JSON logs of all operations
- Correlation with trace IDs for debugging
- Error details with stack traces
- Authentication and connection events
Connecting to Your Monitoring Stack
Jaeger (Distributed Tracing)
# Search traces by service
service:ms365-mcp-server
# Filter by operation type
mcp.operation:mail
# Find errors
error:true
Prometheus/Grafana (Metrics)
# Operation rate
rate(mcp_operations_total[5m])
# Error rate
rate(mcp_errors_total[5m])
# 95th percentile latency
histogram_quantile(0.95, mcp_operation_duration)
Log Analysis
Search by:
- Trace ID for correlated debugging
- Operation category (authentication, file_operations, etc.)
- Error patterns and stack traces
File Structure
office365-mcp-server/
āāā Dockerfile # Container definition with dependencies
āāā docker-compose.yml # Container orchestration
āāā supervisord.conf # Process management inside container
āāā entrypoint.sh # Container startup script
āāā mcp-wrapper.sh # MCP server wrapper with telemetry
āāā .env # Environment configuration
āāā .gitignore # Git ignore patterns
āāā telemetry/ # OpenTelemetry instrumentation
ā āāā package.json # Telemetry dependencies
ā āāā instrumentation.js # OTEL SDK configuration
ā āāā mcp-proxy.js # Instrumented MCP proxy
āāā config/ # Persistent configuration (created at runtime)
āāā tokens/ # OAuth token storage (created at runtime)
āāā ssh_keys/ # SSH keys for authentication (optional)
āāā logs/ # Application logs (created at runtime)
Security Considerations
Credential Storage
- OAuth tokens stored in persistent Docker volume
- SSH password authentication (can be replaced with key-based auth)
- No hardcoded credentials in container images
Network Security
- SSH connection on localhost only (port 2222)
- No direct external access to MCP server
- TLS for all MS-365 API communications
Best Practices
- Change default SSH password
- Use SSH key authentication for production
- Monitor authentication logs
- Regularly rotate OAuth tokens
Troubleshooting
Container Won't Start
# Check container logs
docker-compose logs ms365-mcp
# Common issues:
# 1. Port 2222 already in use
# 2. Permission issues with volumes
# 3. Missing dependencies
SSH Connection Fails
# Test SSH connection manually
ssh -p 2222 mcp@localhost -o StrictHostKeyChecking=no
# Check if sshpass is installed
which sshpass
# Verify container is listening
docker exec ms365-mcp-server netstat -tlnp | grep 2222
MCP Server Not Working
# Check MCP server directly
docker exec -it ms365-mcp-server npx @softeria/ms-365-mcp-server --help
# Test authentication
docker exec -it ms365-mcp-server npx @softeria/ms-365-mcp-server --login
# Check for missing dependencies
docker exec -it ms365-mcp-server ldd /usr/local/lib/node_modules/@softeria/ms-365-mcp-server/node_modules/keytar/build/Release/keytar.node
Telemetry Not Working
# Check OTEL configuration
docker exec ms365-mcp-server env | grep OTEL
# Test OTEL collector connectivity
docker exec ms365-mcp-server curl -v $OTEL_EXPORTER_OTLP_ENDPOINT/v1/traces
# Check telemetry logs
docker exec ms365-mcp-server tail -f /logs/mcp-operations.log
Claude Desktop Integration Issues
# Verify configuration file
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
# Check Claude Desktop logs (if available)
# Restart Claude Desktop after configuration changes
Advanced Configuration
SSH Key Authentication
For enhanced security, replace password authentication with SSH keys:
-
Generate SSH key pair:
ssh-keygen -t rsa -b 4096 -f ./ssh_keys/mcp_key -
Update docker-compose.yml to mount the key:
volumes: - ./ssh_keys:/home/mcp/.ssh:ro -
Update Claude Desktop config:
{ "mcpServers": { "ms365": { "command": "ssh", "args": [ "-i", "/path/to/ssh_keys/mcp_key", "-p", "2222", "-o", "StrictHostKeyChecking=no", "mcp@localhost", "/usr/local/bin/mcp-wrapper.sh" ] } } }
Custom Telemetry Configuration
Sampling Configuration
# Sample 10% of operations for high-volume environments
TELEMETRY_SAMPLE_RATE=0.1
Custom OTEL Headers
# For authenticated OTEL collectors
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-token,X-Custom-Header=value"
Resource Attributes
# Additional resource attributes for better identification
OTEL_RESOURCE_ATTRIBUTES="deployment.environment=production,host.name=raspberrypi,service.instance.id=mcp-001"
Performance Tuning
Resource Limits
Add resource limits to docker-compose.yml:
services:
ms365-mcp:
# ... other configuration
deploy:
resources:
limits:
cpus: '0.5'
memory: 512M
reservations:
cpus: '0.25'
memory: 256M
Telemetry Optimization
# Reduce telemetry overhead for high-volume scenarios
TELEMETRY_SAMPLE_RATE=0.1 # Sample 10% of operations
OTEL_LOG_LEVEL=warn # Reduce telemetry logging
TELEMETRY_LOG_OPERATIONS=false # Disable operation logging
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Test with your setup
- Submit a pull request
License
[Your License Here]
Support
For issues and questions:
- Check the troubleshooting section above
- Review container logs:
docker-compose logs ms365-mcp - Open an issue in this repository
Note: This setup provides comprehensive monitoring and observability for MS-365 MCP operations. The telemetry data helps with debugging, performance optimization, and understanding usage patterns.