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:beta

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

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 " }
    }
  }
}

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

Providers

> 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 run everywhere; IMAP/SMTP, CalDAV and CardDAV require a Node.js runtime (CLI or Docker), not Cloudflare Workers.

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 · Cloudflare Workers
• 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