mail-cal-drive-mcp

A self-hosted Model Context Protocol (MCP) server for multi-account email, calendar, and cloud storage. Connect Microsoft 365, Google Workspace, and IMAP accounts to any MCP client — Claude Desktop, Claude Code, VS Code, Cursor, and more.

Runs locally in Docker with Postgres. Credentials encrypted at rest. Survives reboots without re-authorization.

Prerequisites

• Docker and Docker Compose

• Node.js 20+ (for local development only)

Related MCP server: productivity-mcp

Quick Start

# 1. Clone
git clone https://github.com/rumbitopi/mail-cal-drive-mcp.git
cd mail-cal-drive-mcp

# 2. Configure
cp .env.example .env

# 3. Generate keys (run 3 times — one for each)
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
# Paste into .env as POSTGRES_PASSWORD, CREDENTIAL_ENCRYPTION_KEY, and API_KEY
# Update DATABASE_URL to use the same POSTGRES_PASSWORD

# 4. Start (server runs with zero providers — configure them later)
docker compose up --build -d

# 5. Verify health
curl http://localhost:3100/health

# 6. Verify MCP
curl -X POST http://localhost:3100/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}},"id":1}'

Architecture

┌──────────────────────────────────────────────┐
│  Docker Compose                              │
│  ┌─────────────┐    ┌──────────────┐         │
│  │ workspace   │◄──►│ postgres:5432│         │
│  │ -mcp :3100  │    │ (persistent) │         │
│  │ Streamable  │    └──────────────┘         │
│  │ HTTP + Auth │                             │
│  └─────────────┘                             │
└──────────────────────────────────────────────┘

Protocol: MCP over Streamable HTTP (2024-11-05), MCP SDK 1.25.3

What persists across reboots (in Postgres):

• Credentials (AES-256-GCM encrypted)

• MSAL token cache (silent Microsoft refresh — no re-auth)

• Pending auth flows (survive restarts mid-auth)

What's ephemeral (in memory):

• MCP sessions (clients auto-reconnect)

Client Configuration

Claude Desktop

Claude Desktop speaks stdio, not HTTP. supergateway bridges the two.

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "workspace": {
      "command": "npx",
      "args": [
        "-y", "supergateway",
        "--streamableHttp", "http://localhost:3100/mcp",
        "--header", "Authorization: Bearer YOUR_API_KEY"
      ]
    }
  }
}

Claude Code

Add to .claude/settings.local.json in your project:

{
  "mcpServers": {
    "workspace": {
      "type": "streamable-http",
      "url": "http://localhost:3100/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

VS Code (GitHub Copilot)

Add to .vscode/settings.json:

{
  "github.copilot.chat.mcpServers": {
    "workspace": {
      "type": "streamable-http",
      "url": "http://localhost:3100/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "workspace": {
      "url": "http://localhost:3100/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Provider Setup

Microsoft 365

Uses device code flow — no redirect URI needed.

Azure App Registration

1. Go to Azure Portal → Azure Active Directory → App registrations → New registration

2. Name: Workspace MCP (or anything)

3. Supported account types: "Accounts in any organizational directory and personal Microsoft accounts"

4. Redirect URI: Leave blank

5. Click Register

Enable Public Client Flow

1. Go to your app → Authentication

2. Under Advanced settings, set "Allow public client flows" to Yes

3. Click Save

Add API Permissions

1. Go to API permissions → Add a permission → Microsoft Graph → Delegated permissions

2. Add:

   • Mail.ReadWrite, Mail.Send

   • Calendars.ReadWrite, Calendars.Read.Shared

   • Files.ReadWrite, Files.ReadWrite.All

   • User.Read, offline_access

3. Click "Grant admin consent" if you're an admin

Configure .env

MS_ENABLED=true
MS_CLIENT_ID=<Application (client) ID from Overview page>
MS_TENANT_ID=<Directory (tenant) ID, or "common" for multi-tenant>

Connect

Call auth_start with provider: "microsoft". You'll get a URL and code. Visit the URL, enter the code, sign in. Then call auth_complete. One-time setup — refresh tokens persist across reboots.

Google Workspace

Uses OAuth callback flow — requires a redirect URI.

Google Cloud Setup

1. Go to Google Cloud Console → create or select a project

2. Enable APIs: Gmail API, Google Calendar API, Google Drive API

3. OAuth consent screen:

   • User Type: External (or Internal for Workspace)

   • Add scopes: gmail.modify, gmail.labels, calendar, calendar.events, drive, drive.file

   • Add yourself as a test user

4. Credentials → Create OAuth client ID:

   • Type: Web application

   • Redirect URI: http://localhost:3100/auth/google/callback

Configure .env

GOOGLE_ENABLED=true
GOOGLE_CLIENT_ID=<Client ID>
GOOGLE_CLIENT_SECRET=<Client Secret>
GOOGLE_REDIRECT_URI=http://localhost:3100/auth/google/callback

Connect

Call auth_start with provider: "google". Open the URL, sign in, grant permissions. The callback saves your tokens. Then call auth_complete. One-time setup.

IMAP

No external setup needed — provide credentials directly.

Connect

Call auth_start with:

provider: "imap"
accountName: "Personal Email"
email: "user@example.com"
imapHost: "imap.example.com"
imapPort: 993
imapUsername: "user@example.com"
imapPassword: "your-app-password"
imapTls: true

No auth_complete needed — IMAP accounts are ready immediately.

Common IMAP Servers

MCP Tools (36 total)

Authentication (4)

Email (10)

Calendar (8)

Drive (14)

Tool Parameter Reference

get_attachment

Returns text content for text-based files, or an MCP EmbeddedResource with blob for binary files (PDF, images, etc.). Max 5MB.

search_messages

create_event

bulk_mail_action

find_free_time

upload_file

share_file

Environment Variables

Endpoints

Security

This server is designed for localhost use only. Do not expose it to the internet without additional hardening.

• Encryption at rest: All credentials, MSAL token cache, and pending auth flows encrypted with AES-256-GCM before storage in Postgres

• Bearer auth: Timing-safe token comparison (crypto.timingSafeEqual) on all protected endpoints

• Session limits: Max 100 concurrent sessions, 30-minute TTL with automatic eviction

• Network: Binds to 127.0.0.1 only — not accessible from other machines

• Body size: 10MB request limit to prevent memory exhaustion

• IMAP note: IMAP credentials are passwords (not OAuth tokens) — encrypted at rest, but inherently less secure than OAuth. Use app passwords where possible.

• Logging: All logs to stderr (MCP requirement). No tokens, passwords, or keys logged.

• Token rotation: To rotate the encryption key, generate a new one, re-run auth_start for each account, and update .env. There is no in-place re-encryption (accounts must be re-authorized).

See SECURITY.md for vulnerability reporting.

Troubleshooting

Container won't start

• Check docker compose logs workspace-mcp for errors

• Verify DATABASE_URL matches the Postgres container credentials

• Ensure Postgres is healthy: docker compose logs postgres

Microsoft device code expired

• Device codes expire after 15 minutes. Call auth_start again for a fresh code.

Google OAuth: "Access blocked" or consent screen issues

• Make sure your Google Cloud app is in "Testing" mode with your email added as a test user

• Verify the redirect URI in Google Cloud Console matches GOOGLE_REDIRECT_URI exactly

IMAP connection refused

• Verify host, port, and TLS settings for your provider

• Most providers require an App Password when 2FA is enabled (not your regular password)

• Check if your provider blocks third-party IMAP access (Gmail: enable "Less secure apps" or use App Password)

"Invalid or expired session" on tool calls

• MCP sessions expire after 30 minutes of inactivity and are lost on container restart. Your client should auto-reconnect. If not, restart the client.

Development

# Install dependencies
npm install

# Start with hot reload (requires local Postgres on DATABASE_URL)
npm run dev

# Build TypeScript
npm run build

# Production start
npm start

# Run tests
npm test

# Type check
npm run typecheck

# Migrate credentials from old file-based storage
DATABASE_URL=... CREDENTIAL_ENCRYPTION_KEY=... npm run migrate

Project Structure

mail-cal-drive-mcp/
├── src/
│   ├── index.ts              # Entry point
│   ├── server.ts             # Express server
│   ├── config.ts             # Environment config
│   ├── logger.ts             # Structured console logger
│   ├── auth/
│   │   ├── types.ts          # Credential interfaces
│   │   ├── storage.ts        # Postgres credential storage
│   │   └── bearer.ts         # Bearer token middleware
│   ├── storage/
│   │   ├── postgres.ts       # Postgres client + encrypted CRUD
│   │   ├── msal-cache.ts     # MSAL cache plugin (Postgres)
│   │   └── pending-flows.ts  # Pending auth flow storage
│   ├── providers/
│   │   ├── base.ts           # Abstract interfaces
│   │   ├── types.ts          # Shared types
│   │   ├── microsoft/        # Graph API (mail, calendar, drive)
│   │   ├── google/           # Google APIs (Gmail, Calendar, Drive)
│   │   └── imap/             # ImapFlow (mail only)
│   ├── mcp/
│   │   ├── handler.ts        # MCP request routing
│   │   ├── session.ts        # Session management
│   │   └── tools/            # 35 MCP tools
│   └── utils/                # Timezone, recurrence, MIME helpers
├── db/migrations/            # Postgres schema
├── docker-compose.yml
├── Dockerfile
└── .env                      # Configuration (gitignored)

License

MIT