mcp-ecc
mcp-ecc provides MCP tools to authenticate accounts and manage email, calendar, and contacts across providers.
Authenticate/register Google, Microsoft, Zoho, or IMAP/SMTP accounts with OAuth device flow, tenant/client settings, or app passwords.
Email: list/search recent emails by folder, fetch message bodies/metadata, send plain text or HTML emails, archive/mark read/unread/star, and delete messages.
Calendar: list events in a time range, create events with attendees/descriptions, update existing events, and delete events.
Contacts: search contacts by name/query, create contacts with name/email/phone, and delete contacts.
Most operations require an
accountIdto target a specific authenticated account.
Integrates with Gmail as part of Google Workspace for email, calendar, and contacts.
Integrates with Google Workspace (Gmail, Google Calendar, Google Contacts) via OAuth 2.0 Device Authorization Grant, allowing email management, calendar events, and contact operations.
Supports iCloud mail via IMAP/SMTP with app passwords for email operations.
Integrates with Zoho Mail for email, calendar, and contacts via their API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-ecc show my calendar events for today"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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:latestPublish 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 usersThen 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/.envNote 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 --helpPersisting 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:latestAlternatively, 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:latestBehind 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.comIf 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 /setupEither 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 hostsFrom source
git clone https://github.com/karljsamuel/mcp-ecc.git
cd mcp-ecc
npm install
npm run build
node packages/cli/dist/bin.js --helpRelated 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_KEYusing 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_KEYis 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
Set
MCP_ENCRYPTION_KEYto the new key.List the old key as
MCP_ENCRYPTION_KEY_PREVIOUSin the form"<generation>:<key>"(comma or whitespace separated for several).Call
rotateEncryptionKeys(batchSize)on the storage adapter — rows are re-encrypted in batches and both generations decrypt during the changeover.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 | 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.syncFull reference with input schemas: docs/mcp-tools.md
Documentation
Getting started — overview and quick start
CLI reference — every
mcp-ecccommand and workflowAuth & users — multi-user model, bootstrap, per-user API keys
Accounts & identity — name vs slug
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
Available Tools
13 toolsauthenticate_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
Scored across 13 tools
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.
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.
13 tools cover authentication, calendar, contacts, and email comprehensively without being overwhelming. The count is well-scoped for a multi-domain server.
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
Related MCP Connectors
MCP server for Nylas — read email, calendars, events and contacts, and send email or create events.
Hosted email MCP for your own Gmail, Outlook.com, Microsoft 365, iCloud or IMAP inbox: read, search, draft, reply in thread, forward and file mail. It moves or flags up to 500 messages in one call, and a send leaves exactly one copy in Sent. A calendar is a separate connection, and connecting one adds diary and scheduling tools.
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
Hosted MCP server with managed OAuth for 15+ toolkits: Google Workspace, Fitbit, Oura, Kalshi, etc.
Related MCP Servers
- FlicenseAqualityCmaintenanceLocal-first MCP server for agents that need to work across multiple Gmail and Microsoft 365 accounts without cloud token storage.6-
- FlicenseAqualityDmaintenanceA 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.61-
- AlicenseNot gradedqualityDmaintenanceA 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.1MIT
- AlicenseBqualityBmaintenanceA unified MCP server for email access across Gmail, Outlook, iCloud, and generic IMAP providers, enabling search, send, organize, and batch operations.36208 npm26MIT