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
• sshpass installed: 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

1. Restart Claude Desktop to pick up the configuration
2. Start a new conversation in Claude Desktop
3. First-time setup: The MCP server will prompt for MS-365 authentication:

   Please authenticate with Microsoft 365 by visiting: https://login.microsoftonline.com/...
   

4. Complete OAuth flow in your browser
5. 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/category
• mcp.operation.duration - Histogram of operation durations
• mcp.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:

1. Generate SSH key pair:

   ssh-keygen -t rsa -b 4096 -f ./ssh_keys/mcp_key
   

2. Update docker-compose.yml to mount the key:

   volumes:
     - ./ssh_keys:/home/mcp/.ssh:ro
   

3. 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

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test with your setup
5. 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.