io.github.karljsamuel/mcp-ecc

---

mcp-ecc aggregates your mail, calendar and contacts into standardised MCP tools (mail.*, calendar.*, contacts.*, accounts.*) so any MCP client — Claude, Cursor, and others — can work with all of them uniformly.

• One OAuth consent per cloud provider covers mail + calendar + contacts
• Multi-user — users self-manage their own accounts, each with a per-user MCP API key
• Credentials encrypted at rest (AES-256-GCM)
• Self-hostable — single container serving a web admin UI, REST API and the MCP endpoint on one port

---

Quick start

Docker

docker run -d --name mcp-ecc \
  -p 3001:3001 \
  -e MCP_ENCRYPTION_KEY="$(openssl rand -hex 32)" \
  karljsamuel/mcp-ecc:latest

Open http://localhost:3001 → create the admin account → add your provider accounts.

CLI (npm)

npm install -g mcp-ecc
mcp-ecc            # interactive TUI — login, add accounts, manage everything
mcp-ecc start      # stdio MCP server for agent hosts

From source

git clone https://github.com/karljsamuel/mcp-ecc.git
cd mcp-ecc
npm install
npm run build
node packages/cli/dist/bin.js --help

---

Upgrade and encryption migration

Important for existing installations: install and run the latest 0.6.x migration release before upgrading to 0.7.x.

The migration release changes credential encryption from the discontinued CryptoJS implementation to platform cryptography APIs:

• Node.js SQLite uses node:crypto with authenticated AES-256-GCM.
• Cloudflare D1 uses the Workers Web Crypto API with authenticated AES-256-GCM.
• Existing 0.6.x ciphertext is read once and automatically re-encrypted in the new format.
• New AES-256-GCM values are authenticated and migration is fail-closed.
• Legacy CryptoJS ciphertext has no authentication tag; if it is tampered with, its integrity cannot be cryptographically verified. Back up the database and treat failed or unexpected legacy decryptions as migration failures; values are never overwritten unless decryption succeeds.
• Keep the same MCP_ENCRYPTION_KEY during the upgrade.

After the migration release has successfully started and accessed the existing data, upgrade to 0.7.x. Version 0.7.x removes the legacy CryptoJS reader. Back up the SQLite database or D1 database before upgrading.

Connecting an MCP client

Point your client at the HTTP endpoint with your per-user API key (shown in the web UI under Settings):

{
  "mcpServers": {
    "mcp-ecc": {
      "type": "http",
      "url": "http://localhost:3001/mcp",
      "headers": { "Authorization": "Bearer <your-api-key>" }
    }
  }
}

Agents can read SKILL.md or llms.txt for guided, automated setup.

---

Providers

Provider	Mail	Calendar	Contacts	Authentication
Google (Gmail, Calendar, People)	✅	✅	✅	OAuth 2.0
Microsoft 365 / Outlook (Graph)	✅	✅	✅	OAuth 2.0
Zoho (Mail, Calendar, Contacts)	✅	✅	✅	OAuth 2.0
IMAP / SMTP (any mail server)	✅	❌	❌	App password
CalDAV (Nextcloud, Radicale, BAIKAL)	❌	✅	❌	Password
CardDAV	❌	❌	✅	Password

Microsoft 365: app passwords are being retired — use OAuth (Microsoft Graph) only.

CalDAV/CardDAV compatibility: the providers implement standard WebDAV (CalDAV RFC 4791, CardDAV RFC 6352) with Basic auth and should work with any standards-compliant server. Tested against Radicale 3.7.8. Not tested against other servers; OAuth-only providers (e.g. iCloud without an app-specific password) are not supported.

Deployment notes: Google/Microsoft/Zoho/IMAP/SMTP/CalDAV/CardDAV run under Node.js (CLI or Docker). Cloudflare D1 can be used as a hosted alternative for the local SQLite database.

---

MCP tools

mail.listFolders · mail.listMessages · mail.getMessage · mail.sendMessage
mail.searchMessages · mail.moveMessage · mail.setFlags · mail.deleteMessage

calendar.listCalendars · calendar.listEvents · calendar.getEvent · calendar.freeBusy
calendar.createEvent · calendar.updateEvent · calendar.deleteEvent

contacts.list · contacts.get · contacts.create · contacts.update
contacts.delete · contacts.search

accounts.list · accounts.get · accounts.add · accounts.remove · accounts.sync

Full reference with input schemas: docs/mcp-tools.md

---

Documentation

• Getting started — overview and quick start
• CLI reference — every mcp-ecc command and workflow
• Auth & users — multi-user model, bootstrap, per-user API keys
• Accounts & identity — name vs slug
• Deployment — CLI · Docker
• Providers — Google · Microsoft 365 · Zoho · IMAP/SMTP · CalDAV/CardDAV

---

Contributing

Feature branches off dev; PRs against dev. Run npm run build to compile all packages. Keep Changelog.md and docs/ in sync.

Support & Contributions

If you find mcp-ecc useful, consider supporting its development:

• PayPal: paypal.me/KarlJosephSamuel
• GitHub Sponsors: github.com/sponsors/karljsamuel
• Ko-fi: ko-fi.com/karljsamuel
• Patreon: patreon.com/karljsamuel
• Buy Me a Coffee: buymeacoffee.com/karljsamuel

---

License