Skip to main content
Glama

mcp-ecc

Email · Calendar · Contacts — one MCP server for all your accounts

A Model Context Protocol (MCP) server that lets AI assistants read, write and manage your email, calendar and contacts — across Google, Microsoft 365/Outlook, Zoho, and any IMAP/SMTP, CalDAV or CardDAV account — from a single interface.

License TypeScript Version Sponsor Node MCP Docker Multi-arch


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 127.0.0.1:3001:3001 \
  -v mcp-ecc-data:/data \
  karljsamuel/mcp-ecc:latest

Publish the port on 127.0.0.1 as above. The container listens on 0.0.0.0 internally so the published port can reach it — the loopback restriction on the host side is what keeps it off your network. Put a reverse proxy or tunnel in front before widening that.

With no configuration the container starts in setup mode. Read the one-time setup token from the logs:

docker logs mcp-ecc 2>&1 | grep "Setup token:"

Then open http://127.0.0.1:3001/setup, paste the token, and work through the wizard: choose SQLite or Cloudflare D1, let it verify the connection, generate an encryption key, set the server options, and create the first admin account.

While setup is incomplete, every API route except /api/setup/* answers 503. The setup token is the only thing protecting that page until an admin exists, so do not publish the port beyond loopback until setup has completed.

Volume permissions (bind mounts)

The container runs as uid 1001 (the mcp-ecc user), not root. A named volume is seeded with that ownership automatically. A bind mount is not — Docker mounts the host directory exactly as it is, so if it is owned by root the app can read it but cannot write, and you get EACCES: permission denied on /data (or a database that never initialises).

If you use a bind mount — as docker-compose.yml does with ./data:/data — prepare the directory with the container's uid before starting:

mkdir -p ./data
sudo chown -R 1001:1001 ./data
sudo chmod 2775 ./data     # optional: keeps group access for host users

Then confirm from inside the container:

docker exec mcp-ecc sh -c 'touch /data/.probe && rm /data/.probe && echo writable'

Symptoms of getting this wrong: a permission denied line in docker logs, a crash/restart loop, and a 502 from your reverse proxy or tunnel because nothing ends up listening on the published port.

The .env must sit beside docker-compose.yml

Compose interpolates ${MCP_ENCRYPTION_KEY}, ${CLOUDFLARE_API_TOKEN} and friends from a .env in the same directory as the compose file. If that file is missing or misnamed, every variable resolves to an empty string and the container starts in setup mode — which looks like an outage: /health returns 200 while /mcp and /api/* return 503, and the logs say is unconfigured and running in SETUP MODE.

Check that the file is where compose expects it, and that the keys are actually present (this prints variable names only, never values):

ls -la /path/to/compose-dir/.env
grep -oE '^[A-Z_]+=' /path/to/compose-dir/.env

Note that environment variables are captured when a container is created. If you edit .env or rotate a credential, recreate the container — docker compose up -d --force-recreate — or the running container keeps the old values.

The CLI is on PATH inside the container

The image links mcp-ecc into /usr/local/bin (→ /app/packages/cli/dist/bin.js), so the CLI is available by name with nothing installed on the host — for stdio MCP clients, maintenance, and the setup flow:

docker exec -it mcp-ecc mcp-ecc --help

Persisting the generated configuration

A .env written inside a container is lost when the container is recreated, so the wizard hands you the content through a copy button instead of writing it. Put it somewhere durable and give it to the container by reference:

# paste the copied content into ./mcp-ecc.env first
docker rm -f mcp-ecc
docker run -d --name mcp-ecc \
  -p 127.0.0.1:3001:3001 \
  -v mcp-ecc-data:/data \
  --env-file ./mcp-ecc.env \
  karljsamuel/mcp-ecc:latest

Alternatively, mount a writable location and point MCP_ENV_FILE at it. The wizard then writes the file itself — no copy step, no restart — because the path is known to survive:

docker run -d --name mcp-ecc \
  -p 127.0.0.1:3001:3001 \
  -v mcp-ecc-data:/data \
  -e MCP_ENV_FILE=/data/.env \
  karljsamuel/mcp-ecc:latest

Behind Cloudflare Tunnel or another reverse proxy

Set PUBLIC_URL to the public address — OAuth callbacks and the MCP endpoint URL are built from it, so localhost will break them:

-e PUBLIC_URL=https://mcp-ecc.example.com

If you put Cloudflare Access in front, leave a bypass for /mcp: MCP clients authenticate with per-user Bearer keys and cannot complete an interactive login.

Web UI

mcp-ecc setup          # or: start the API unconfigured and open /setup

Either path walks the same steps: pick SQLite or Cloudflare D1, verify the connection actually works, generate an encryption key, set the server options, write .env, then create the first admin account.

CLI (npm)

npm install -g mcp-ecc
mcp-ecc setup      # first run — writes .env and creates the admin account
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

Related MCP server: outlook-mcp-server

Upgrading to 0.7.0

This release invalidates stored credentials. Every account must be re-authenticated once after upgrading, and per-user API keys are regenerated. Back up your database first if you want a rollback path.

What changed

Credential encryption was rebuilt from scratch:

  • One canonical ciphertext format shared by both backends: base64(iv[12] || authTag[16] || ciphertext), AES-256-GCM.

  • Per-owner key derivation. The data key is derived with HKDF-SHA256 over MCP_ENCRYPTION_KEY using the owner id, instead of one global key. A value encrypted for one user cannot be decrypted as another.

  • Key rotation is supported. Each encrypted row records a key generation in the database, so you can move to a new key and re-encrypt in batches while both generations remain readable.

  • CryptoJS is gone — the dependency, the legacy reader, and the migration path with it. There is no automatic migration from pre-0.7 ciphertext.

  • No fallback key. A missing or placeholder MCP_ENCRYPTION_KEY is a hard startup error. The key is never read from or written to the database.

Why you must re-authenticate

Values written by earlier versions cannot be decrypted by this one, by design. Everything encrypted at rest — OAuth refresh tokens, OAuth client secrets, IMAP/SMTP app passwords — becomes unreadable. You can start from a fresh database, or upgrade in place and re-run the auth flow per account.

If you were told to run 0.6.x first

That instruction is obsolete. 0.6.x was an intermediate step toward a platform-crypto format; 0.7.0 supersedes it and removes both the intermediate step and the reader it depended on. Going straight from 0.6.0 to 0.7.0 is the supported path.

Rotating the key

  1. Set MCP_ENCRYPTION_KEY to the new key.

  2. List the old key as MCP_ENCRYPTION_KEY_PREVIOUS in the form "<generation>:<key>" (comma or whitespace separated for several).

  3. Call rotateEncryptionKeys(batchSize) on the storage adapter — rows are re-encrypted in batches and both generations decrypt during the changeover.

  4. Once every row is rotated, drop MCP_ENCRYPTION_KEY_PREVIOUS.

Set MCP_ENCRYPTION_KEY_GENERATION explicitly when you rotate, so a later key is not renumbered into an earlier generation's slot.

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


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:


License

Available Tools

13 tools
authenticate_accountB

Authenticate and register a Google, Microsoft, Zoho, or IMAP/SMTP account. Supports headless OAuth (device code flow) with custom client/tenant configurations.

Inputs: provider (required), accountId (required), config, clientId, +3 more.

calendar_create_eventC

Create a calendar event.

Inputs: title (required), endTime (required), accountId (required), startTime (required), +2 more.

calendar_delete_eventC

Delete/remove a calendar event.

Inputs: eventId (required), accountId (required).

calendar_list_eventsB

View scheduled events/appointments within a time range.

Inputs: accountId (required), endTime, startTime.

calendar_update_eventC

Modify an existing calendar event.

Inputs: eventId (required), patches (required), accountId (required).

contacts_create_contactC

Inject a new contact into the address book.

Inputs: name (required), email (required), accountId (required), phone.

contacts_delete_contactC

Remove a contact entry.

Inputs: accountId (required), contactId (required).

contacts_search_contactsC

Find contact entries by name or query term.

Inputs: query (required), accountId (required).

email_delete_emailC

Move email to Trash or delete permanently.

Inputs: accountId (required), messageId (required).

email_get_emailC

Fetch the body and metadata of a specific email.

Inputs: accountId (required), messageId (required).

email_list_emailsC

Search or view recent emails.

Inputs: accountId (required), limit, query, folder.

email_manage_emailB

Archive, mark read/unread, or star an email.

Inputs: action (required), accountId (required), messageId (required).

email_send_emailC

Send a plain text or HTML email.

Inputs: to (required), body (required), subject (required), accountId (required), +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 13 tools

    Disambiguation5/5

    Tools are clearly grouped by domain (calendar, contacts, email) with distinct actions per domain. There is no overlap in functionality, and each tool serves a unique purpose.

    Naming Consistency5/5

    All tools follow a consistent 'domain_action' pattern (e.g., calendar_create_event, email_send_email) with only 'authenticate_account' lacking a prefix, which is acceptable as a singleton.

    Tool Count5/5

    13 tools cover authentication, calendar, contacts, and email comprehensively without being overwhelming. The count is well-scoped for a multi-domain server.

    Completeness4/5

    Calendar and email have full CRUD-like coverage; contacts lack an update tool, which is a minor gap. Overall, the tool surface covers core workflows effectively.

    Maintenance

    ActivityActive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      C
      maintenance
      Local-first MCP server for agents that need to work across multiple Gmail and Microsoft 365 accounts without cloud token storage.
      6
      -
    • F
      license
      A
      quality
      D
      maintenance
      A lightweight MCP server for personal Microsoft Outlook/Hotmail accounts, enabling email search, reading, attachment management, and folder operations via Microsoft Graph API with OAuth device-code flow.
      6
      1
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      A self-hosted MCP server for managing email, calendar, and cloud storage across Microsoft 365, Google Workspace, and IMAP accounts, enabling natural language interaction through any MCP client.
      1
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      A unified MCP server for email access across Gmail, Outlook, iCloud, and generic IMAP providers, enabling search, send, organize, and batch operations.
      36
      208 npm
      26
      MIT