mailcow-dav-mcp

Works with

🇬🇧 English · 🇮🇹 Italiano

An MCP server that gives AI assistants access to the 📇 address book (CardDAV), 📅 calendar (CalDAV) and ✅ tasks of a mailcow mailbox. It uses the SOGo DAV endpoint that mailcow already publishes at /SOGo/dav/<mailbox>/, so you don't need to change anything on the mailcow side.

📚 Contents

• ✨ Features

• 📋 Requirements

• 🚀 Quick start

• 🔌 Connect your client: Claude Code · Claude Desktop · Codex · ChatGPT · other HTTP clients

• ⚙️ Configuration

• 🔒 Security

• 💡 Usage notes

• 🩺 Troubleshooting

• 🛠️ Development

• 🆘 Support

Related MCP server: caldav-mcp

✨ Features

🩺 dav_status checks the credentials and lists your address books and calendars.

Fields: prefix, given/middle/family name, suffix, nickname, typed emails and phones (work:, cell:…), company and department, job title and role, notes, birthday, anniversary, spouse, assistant, IM (telegram:@x, skype:id…), time zone, URLs, postal addresses (type:street;city;region;zip;country), tags and photo.

Groups vs tags: groups are Apple-style group vCards (what Apple Contacts and BusyContacts show). Tags are the CATEGORIES of each contact (what SOGo shows). Both are supported.

📋 Requirements

• 🐄 A mailcow mailbox (any recent mailcow with SOGo enabled).

• ⚡ uv (recommended), or Python 3.11+ with pip.

• 💻 macOS, Linux or Windows.

🚀 Quick start

1️⃣ Create a mailcow app password

Use an app password, not your mailbox password: you can limit it to DAV and revoke it at any time.

1. Log in to the mailcow UI as the mailbox user.

2. Open Mailbox → Edit → App passwords and add a new one.

3. Under Allow for, select only DAV/SOGo.

4. Copy the password. You need it in the next step.

2️⃣ Store the credentials

Keep them in a dedicated file that only your user can read, so the password never ends up in a client's config:

mkdir -p ~/.config/mailcow-dav-mcp
cat > ~/.config/mailcow-dav-mcp/.env <<'EOF'
MAILCOW_DAV_URL=https://mail.example.com
MAILCOW_DAV_USER=you@example.com
MAILCOW_DAV_PASSWORD=your-app-password
MAILCOW_DAV_TIMEZONE=Europe/Rome
EOF
chmod 600 ~/.config/mailcow-dav-mcp/.env

Every client then needs only MAILCOW_DAV_ENV_FILE pointing to this file. A template is in .env.example.

3️⃣ Install and test

Option A: no clone (recommended). uvx downloads and runs the server on demand:

MAILCOW_DAV_ENV_FILE=$HOME/.config/mailcow-dav-mcp/.env \
  uvx --from git+https://github.com/OakNet-io/mailcow-dav-mcp@v0.2.1 mailcow-dav-mcp --check

Option B: from a clone (for development or to pin a version):

git clone https://github.com/OakNet-io/mailcow-dav-mcp.git
cd mailcow-dav-mcp
uv sync                                   # or: python3 -m venv .venv && .venv/bin/pip install -e .
cp .env.example .env && chmod 600 .env    # then edit .env
uv run mailcow-dav-mcp --check

✅ Expected output: OK server=... user=... followed by your address books and calendars.

🔌 Connect your client

claude mcp add mailcow-dav --scope user \
  -e MAILCOW_DAV_ENV_FILE=$HOME/.config/mailcow-dav-mcp/.env \
  -- uvx --from git+https://github.com/OakNet-io/mailcow-dav-mcp@v0.2.1 mailcow-dav-mcp

Check with claude mcp list, or type /mcp inside Claude Code. --scope user makes the server available in every project. Leave it out to add it to the current project only.

Open Settings → Developer → Edit Config, or edit the file directly:

• 🍎 macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• 🪟 Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mailcow-dav": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/OakNet-io/mailcow-dav-mcp@v0.2.1", "mailcow-dav-mcp"],
      "env": {
        "MAILCOW_DAV_ENV_FILE": "/Users/you/.config/mailcow-dav-mcp/.env"
      }
    }
  }
}

Quit Claude Desktop completely and start it again. The tools appear under the tools icon in the chat box. A copy of this snippet is in claude_desktop_config.example.json.

codex mcp add mailcow-dav \
  --env MAILCOW_DAV_ENV_FILE=$HOME/.config/mailcow-dav-mcp/.env \
  -- uvx --from git+https://github.com/OakNet-io/mailcow-dav-mcp@v0.2.1 mailcow-dav-mcp

Or add it by hand to ~/.codex/config.toml. The Codex CLI and the IDE extension share this file:

[mcp_servers.mailcow-dav]
command = "uvx"
args = ["--from", "git+https://github.com/OakNet-io/mailcow-dav-mcp@v0.2.1", "mailcow-dav-mcp"]
env = { MAILCOW_DAV_ENV_FILE = "/Users/you/.config/mailcow-dav-mcp/.env" }

Check with codex mcp list, or /mcp inside a Codex session.

ChatGPT connects only to remote MCP servers over HTTPS: it can't start a local command. Custom MCP servers are available on ChatGPT web for Business and Enterprise/Edu workspaces, subject to the workspace permissions (Create plugins with MCPs). See OpenAI's guide: Connecting custom MCP servers in ChatGPT.

1. Start the server in HTTP mode on your machine or on a server you control. It listens on 127.0.0.1 only:

MAILCOW_DAV_ENV_FILE=$HOME/.config/mailcow-dav-mcp/.env \
  uvx --from git+https://github.com/OakNet-io/mailcow-dav-mcp@v0.2.1 mailcow-dav-mcp --transport http --port 8000

The MCP endpoint is http://127.0.0.1:8000/mcp.

2. Make it reachable by ChatGPT without exposing it. Choose one:

• 🛡️ OpenAI Secure MCP Tunnel (recommended). The server stays private. Follow the tunnel setup in the guide above and point the tunnel at http://127.0.0.1:8000/mcp.

• 🔐 A reverse proxy that adds OAuth, for example an identity-aware proxy in front of the server.

If the tunnel or proxy forwards a public host name, allow it with MAILCOW_DAV_MCP_ALLOWED_HOSTS=mcp.example.com. Otherwise the server rejects the requests with 421 (DNS-rebinding protection).

3. Add it in ChatGPT.

1. Open Plugins, select +, then Add custom MCP server.

2. Enter a name. Under Connection, enter the HTTPS URL, or select Tunnel and choose your tunnel.

3. Configure authentication, then check I understand and want to continue.

4. Select Create as a plugin and review the discovered tools.

5. Install the plugin, start a new chat, type @ and select it.

In the legacy flow (Settings → Apps → Create), enter the endpoint, select Scan Tools, then Create.

Any client that supports Streamable HTTP can use the HTTP mode. To listen on an address other than loopback you must set a bearer token, otherwise the server refuses to start. Generate the token once and keep it in a private file:

mkdir -p ~/.config/mailcow-dav-mcp
(umask 077; openssl rand -hex 32 > ~/.config/mailcow-dav-mcp/token)
export MAILCOW_DAV_MCP_TOKEN="$(cat ~/.config/mailcow-dav-mcp/token)"
MAILCOW_DAV_MCP_ALLOWED_HOSTS=mcp.example.com \
  mailcow-dav-mcp --transport http --host 127.0.0.1 --port 8000

Publish it through a reverse proxy with TLS on the same machine, forwarding https://mcp.example.com/mcp to http://127.0.0.1:8000/mcp. Use --host 0.0.0.0 only on a private network, and never without TLS in front: the token travels in a header. MAILCOW_DAV_MCP_ALLOWED_HOSTS is the public host name the clients use. Without it the server answers 421. On the client machine, read the same token:

• Claude Code: claude mcp add --transport http mailcow-dav https://mcp.example.com/mcp -H "Authorization: Bearer $(cat ~/.config/mailcow-dav-mcp/token)"

• Codex: export MAILCOW_DAV_MCP_TOKEN="$(cat ~/.config/mailcow-dav-mcp/token)" in the shell that starts Codex, then codex mcp add mailcow-dav --url https://mcp.example.com/mcp --bearer-token-env-var MAILCOW_DAV_MCP_TOKEN

⚙️ Configuration

Command line: mailcow-dav-mcp [--check] [--transport stdio|http] [--host H] [--port P] [--path /mcp]

🔒 Security

💡 Usage notes

• 🗓️ Dates are ISO 8601. Without an offset, MAILCOW_DAV_TIMEZONE is used. Explicit offsets (+02:00) are converted to that time zone, keeping the same instant. For all-day events, end is exclusive.

• 📝 In updates, lists (emails, phones, addresses, attendees, urls, categories) replace the existing ones.

• ⏳ Changing only text fields of an event leaves its dates untouched. Moving start keeps the duration. Turning an all-day event into a timed one requires start with a time.

• 🔁 Recurrences are expanded on the client. To change or delete one occurrence, pass the recurrence_id from list_events as occurrence. It keeps working after the occurrence has been moved. On a non-recurring event occurrence is an error: the tool never falls back to the whole event. rrule="" turns a series into a single event and drops its exceptions. Each series is expanded up to 2000 occurrences per request.

• ⏰ New task reminders are relative to the due date, or to the start date when there is no due date. Existing reminders keep their anchor, unless that date is removed.

• ✉️ respond_to_invitation sets your PARTSTAT. SOGo sends the reply to the organizer. SOGo also sends the invitations when you create an event with attendees.

• 🔍 search_contacts scans the whole address book on the client, because SOGo's server-side query matches only some fields. The first search takes about 2–3 seconds for ~700 contacts. Later searches download only the cards whose ETag changed.

• 📤 export_contacts as vcf is an exact copy of every resource, groups included. csv contains contacts only. Resources the server lists but doesn't return are reported in missing. In CSV, list items are separated by | (\| is a literal bar), and cells that start with =, +, - or @ get a leading ' so spreadsheets don't run them as formulas. import_contacts reverses both.

• 📥 import_contacts imports contacts first, then groups, with members rewritten to the UIDs actually used. Members that match no contact are listed in unresolved_members, in the dry run too.

SOGo re-serializes every vCard. If a line is exactly 75 characters long (or 149, 223…), SOGo folds it with an empty continuation line. Apple Contacts and BusyContacts then merge it with the next field (e.g. country IT + CATEGORIES:… → ITCATEGORIES:…). A client can't fix this: create_contact/update_contact return a warning, and check_folding lists the affected contacts. Fix: change the field length (e.g. Italia instead of IT).

🩺 Troubleshooting

Server messages are in English.

🛠️ Development

uv sync --extra dev
uv run --extra dev pytest

For manual integration tests, run Radicale locally. The server expects the SOGo layout <principal>/Contacts/<id>/ and <principal>/Calendar/<id>/, so give the test user write access to nested collections and create them once:

printf 'tester:secret\n' > users
cat > rights <<'EOF2'
[root]
user: .+
collection:
permissions: R

[owner]
user: .+
collection: {user}(/.*)?
permissions: RrWw
EOF2
cat > config <<EOF2
[server]
hosts = 127.0.0.1:5232
[auth]
type = htpasswd
htpasswd_filename = $PWD/users
htpasswd_encryption = plain
[rights]
type = from_file
file = $PWD/rights
[storage]
filesystem_folder = $PWD/data
EOF2
uvx radicale --config ./config &
sleep 3
B=http://127.0.0.1:5232; U=tester:secret
curl -u "$U" -X PROPFIND -H "Depth: 0" "$B/tester/" -o /dev/null   # creates the principal
curl -u "$U" -X MKCOL "$B/tester/Contacts/"
curl -u "$U" -X MKCOL "$B/tester/Calendar/"
curl -u "$U" -X MKCOL -H "Content-Type: application/xml" "$B/tester/Contacts/personal/" --data \
  '<D:mkcol xmlns:D="DAV:" xmlns:C="urn:ietf:params:xml:ns:carddav"><D:set><D:prop><D:resourcetype><D:collection/><C:addressbook/></D:resourcetype></D:prop></D:set></D:mkcol>'
curl -u "$U" -X MKCALENDAR "$B/tester/Calendar/personal/"

Then set MAILCOW_DAV_URL=http://127.0.0.1:5232, MAILCOW_DAV_USER=tester, MAILCOW_DAV_PRINCIPAL_PATH=/tester/.

Contributions are welcome: open an issue to discuss bigger changes first, and add a test for every fix.

🆘 Support

• 📖 Documentation: this README · Italiano

• 🐞 Issues: GitHub Issues

• 💬 Discussions: GitHub Discussions

• 🔐 Security: private advisory

🙏 Acknowledgements

• mailcow and SOGo for the mail and groupware stack

• Model Context Protocol and its Python SDK

• vobject, icalendar, recurring-ical-events, httpx, lxml

📄 License

Released under the MIT License.

⭐ Star the repo if it helps you · 🐄 Made for the mailcow community