mcp-twake-dav

MCP server for Twake.ai — integrate your sovereign Digital Workplace with any MCP-compatible AI assistant

Overview

mcp-twake-dav is a Model Context Protocol (MCP) server that connects any MCP-compatible AI assistant (Claude Desktop, Claude CLI, etc.) to your CalDAV calendars and CardDAV contacts. Compatible with SabreDAV-based servers including Twake, Nextcloud, and other CalDAV/CardDAV implementations.

Key benefits:

• Your data stays on your own servers — sovereign infrastructure
• Works with any MCP-compatible AI assistant
• Full control over calendar and contact data — read and write
• Installable via npm — no local build required
• Secure HTTPS-only connections (except localhost for development)

Features

Calendar Read Tools:

• get_next_event - Find your next upcoming meeting
• get_todays_schedule - View all events scheduled for today
• get_events_in_range - Get events for a date range (natural language: "this week", "next month", etc.)
• search_events - Search events by keyword or attendee name
• list_calendars - List all available calendars
• check_availability - Check free/busy availability for a time range

Calendar Write Tools:

• create_event - Create a new calendar event (with optional recurrence)
• update_event - Update an existing event (partial updates, single occurrence editing)
• delete_event - Delete an event by UID (or single occurrence of recurring event)
• add_alarm - Add a reminder to an event (natural language: "15 minutes", "1 hour", "1 day")
• remove_alarm - Remove a reminder from an event

Invitation Management:

• list_invitations - List pending calendar invitations awaiting your response
• respond_to_invitation - Accept, decline, or tentatively accept an invitation

Contact Read Tools:

• search_contacts - Search contacts by name or organization
• get_contact_details - Get full details for a specific contact
• list_contacts - List all contacts (up to 30)
• list_addressbooks - List all available address books

Contact Write Tools:

• create_contact - Create a new contact
• update_contact - Update an existing contact (partial updates supported)
• delete_contact - Delete a contact by UID

Advanced Features:

• Event status display (CANCELLED, TENTATIVE events clearly marked)
• Attendee participation status (ACCEPTED, DECLINED, TENTATIVE, NEEDS-ACTION)
• Recurring event expansion (RRULE support with safety limits)
• Single occurrence editing (modify or delete individual occurrences of recurring events)
• VALARM reminder management (add/remove alarms with natural language triggers)
• RFC 6638 scheduling inbox support (list and respond to invitations)
• Multi-calendar and multi-addressbook search
• CTag-based caching for improved performance
• Natural language date parsing (powered by chrono-node)
• AI-friendly error messages for troubleshooting
• Case-insensitive search across events and contacts
• Parse-modify-serialize updates (preserves VALARM, X-properties, ATTENDEE, etc.)
• MCP tool annotations (readOnlyHint, destructiveHint, openWorldHint)

Prerequisites

• Node.js >= 18.0.0
• CalDAV/CardDAV Server - A SabreDAV-compatible server such as:
  • Twake
  • Nextcloud
  • OwnCloud
  • SOGo
  • DAVical
  • iCloud (limited support)
• HTTPS Required - Your CalDAV/CardDAV server must use HTTPS (except localhost for development)
• MCP-compatible AI assistant - Claude Desktop, Claude CLI, or any MCP client

Installation

Via npx (recommended — no install needed):

npx mcp-twake-dav

Global install:

npm install -g mcp-twake-dav
mcp-twake-dav

From source (development):

git clone https://github.com/mmaudet/mcp-twake-dav.git
cd mcp-twake-dav
npm install
npm run build

Quick Setup (Recommended)

The easiest way to configure mcp-twake-dav is to use the interactive setup wizard:

npx mcp-twake-dav setup

The wizard will:

1. Ask for your CalDAV/CardDAV server URL
2. Ask for your authentication method and credentials
3. Test the connection and discover your calendars and address books
4. Let you choose default calendar and address book
5. Generate and optionally write the configuration to your Claude Desktop config file

Example session:

  mcp-twake-dav Setup Wizard
  ───────────────────────────
  This wizard will configure mcp-twake-dav for your agent.

CalDAV/CardDAV server URL (e.g., https://dav.example.com): https://dav.linagora.com

Authentication method:
  1. Basic (username/password)
  2. Bearer token (JWT)
Choose [1-2]: 1
Username: [email protected]
Password:

Testing connection...

  Connected successfully!
  Found 4 calendar(s) and 2 address book(s).

Select default calendar:
  1. My Calendar
  2. Shared Calendar
  3. (All)
Choose [1-3]: 1

--- MCP Server Configuration ---

{
  "mcpServers": {
    "mcp-twake-dav": {
      "command": "npx",
      "args": ["-y", "mcp-twake-dav"],
      "env": {
        "DAV_URL": "https://dav.linagora.com",
        "DAV_USERNAME": "[email protected]",
        "DAV_PASSWORD": "********",
        "DAV_DEFAULT_CALENDAR": "My Calendar"
      }
    }
  }
}

Write configuration to config file? [Y/n]: y

  Added "mcp-twake-dav" in claude_desktop_config.json

Setup complete! Restart your agent to apply changes.

Configuration

Environment Variables

Basic Auth (default)

Standard username/password authentication. DAV_AUTH_METHOD can be omitted (defaults to basic).

| Variable | Required | Description | Example | |----------|----------|-------------|---------| | DAV_URL | Yes | CalDAV/CardDAV server base URL (HTTPS required) | https://dav.example.com | | DAV_USERNAME | Yes | Authentication username | [email protected] | | DAV_PASSWORD | Yes | Authentication password | your-password | | DAV_DEFAULT_CALENDAR | No | Default calendar name to query (omit to query all) | My Calendar | | DAV_DEFAULT_ADDRESSBOOK | No | Default address book name to query (omit to query all) | My Contacts |

Bearer Token

JWT Bearer token, sent as Authorization: Bearer <token>.

| Variable | Required | Description | Example | |----------|----------|-------------|---------| | DAV_URL | Yes | CalDAV/CardDAV server base URL (HTTPS required) | https://dav.example.com | | DAV_AUTH_METHOD | Yes | Must be set to bearer | bearer | | DAV_TOKEN | Yes | JWT Bearer token | eyJhbGciOiJSUzI1NiIs... | | DAV_DEFAULT_CALENDAR | No | Default calendar name to query (omit to query all) | My Calendar | | DAV_DEFAULT_ADDRESSBOOK | No | Default address book name to query (omit to query all) | My Contacts |

Optional

| Variable | Description | Example | |----------|-------------|---------| | LOG_LEVEL | Log verbosity: fatal, error, warn, info, debug, trace | info (default) |

Security Note: HTTPS is enforced to prevent credential exposure. Only localhost and 127.0.0.1 are allowed over HTTP for development purposes.

Claude Desktop Configuration

To use mcp-twake-dav with Claude Desktop, add the following to your Claude Desktop configuration file:

Configuration file location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Configuration (Basic Auth):

{
  "mcpServers": {
    "twake": {
      "command": "npx",
      "args": ["-y", "mcp-twake-dav"],
      "env": {
        "DAV_URL": "https://dav.example.com",
        "DAV_USERNAME": "[email protected]",
        "DAV_PASSWORD": "your-password",
        "DAV_DEFAULT_CALENDAR": "My Calendar",
        "DAV_DEFAULT_ADDRESSBOOK": "My Contacts"
      }
    }
  }
}

Configuration (Bearer Token):

{
  "mcpServers": {
    "twake": {
      "command": "npx",
      "args": ["-y", "mcp-twake-dav"],
      "env": {
        "DAV_URL": "https://dav.example.com",
        "DAV_AUTH_METHOD": "bearer",
        "DAV_TOKEN": "your-jwt-token",
        "DAV_DEFAULT_CALENDAR": "My Calendar",
        "DAV_DEFAULT_ADDRESSBOOK": "My Contacts"
      }
    }
  }
}

DAV_DEFAULT_CALENDAR and DAV_DEFAULT_ADDRESSBOOK are optional. When set, tools query only the named calendar/address book by default. Use "all" as a tool parameter to override and search all calendars or address books.

After updating the configuration, restart Claude Desktop for changes to take effect.

Usage Examples

Once configured, you can ask Claude natural language questions about your calendar and contacts:

Calendar queries:

• "What's my next meeting?"
• "What's on my calendar today?"
• "Show my schedule for this week"
• "What meetings do I have next month?"
• "When is my meeting with Pierre?"
• "Find all meetings about the budget"
• "Show me events with Marie as an attendee"
• "Am I free tomorrow afternoon?"
• "What's my first available 45-minute slot this week?"

Calendar management:

• "Create a meeting with Pierre tomorrow at 2pm"
• "Move my 3pm meeting to 4pm"
• "Delete the team sync event"
• "Add a weekly standup every Monday at 9am"
• "Add a 15 minute reminder to my dentist appointment"
• "Remove the reminder from tomorrow's meeting"
• "Move only Tuesday's standup to 10am" (single occurrence)
• "Cancel just Friday's team meeting" (single occurrence)

Invitation management:

• "Do I have any pending invitations?"
• "Accept the team meeting invitation"
• "Decline the conference call"
• "Tentatively accept the lunch meeting"

Contact queries:

• "What's Marie's email address?"
• "Show me Pierre's contact details"
• "Find contacts working at LINAGORA"
• "List all my contacts"
• "Search for contacts named Martin"
• "What address books do I have?"

Contact management:

• "Create a contact for Jean Dupont with email [email protected]"
• "Update Marie's phone number"
• "Delete the contact for [email protected]"

Available Tools

| Tool Name | Description | |-----------|-------------| | get_next_event | Get the next upcoming event. Optional calendar filter | | get_todays_schedule | Get all events for today, sorted by time. Optional calendar filter | | get_events_in_range | Get events for a date range (natural language). Optional calendar filter | | search_events | Search events by keyword or attendee. Optional calendar filter | | check_availability | Check free/busy availability for a time range. Optional calendar filter | | list_calendars | List all available calendars | | create_event | Create a new event with title, start, end, and optional recurrence | | update_event | Update an existing event by UID (partial updates, single occurrence with instanceDate) | | delete_event | Delete an event by UID (or single occurrence with instanceDate) | | add_alarm | Add a reminder to an event (natural language trigger: "15m", "1h", "1d") | | remove_alarm | Remove a reminder from an event by index or remove all | | list_invitations | List pending calendar invitations awaiting response | | respond_to_invitation | Accept, decline, or tentatively accept an invitation by UID | | search_contacts | Search contacts by name or organization. Optional addressbook filter | | get_contact_details | Get full details for a contact by name. Optional addressbook filter | | list_contacts | List contacts (limited to 30). Optional addressbook filter | | list_addressbooks | List all available address books | | create_contact | Create a new contact with name, email, phone, etc. | | update_contact | Update an existing contact by UID (partial updates) | | delete_contact | Delete a contact by UID |

Troubleshooting

Common Issues and Solutions

1. "Configuration validation failed" / Missing environment variables

• Problem: Required environment variables are missing for the selected auth method
• Solution: For basic auth (default): set DAV_URL, DAV_USERNAME, DAV_PASSWORD. For bearer auth: set DAV_URL, DAV_AUTH_METHOD=bearer, DAV_TOKEN

2. "Authentication failed" / 401 Unauthorized

• Problem: Invalid credentials or token
• Solution: For basic auth: verify DAV_USERNAME and DAV_PASSWORD. For bearer auth: verify DAV_TOKEN is valid and not expired

3. "Cannot find server" / DNS resolution error

• Problem: The DAV_URL hostname cannot be resolved
• Solution: Check the spelling of your DAV_URL. Ensure your server is accessible from your network. Try accessing the URL in a web browser

4. "Connection timed out" / Network timeout

• Problem: Server is unreachable or not responding
• Solution: Verify your CalDAV/CardDAV server is online. Check firewall settings. Ensure you have network connectivity to the server

5. "URL must use HTTPS" / SSL certificate error

• Problem: HTTP connection attempted (insecure) or invalid SSL certificate
• Solution: Use HTTPS in your DAV_URL (e.g., https://dav.example.com). For development on localhost, use http://localhost or http://127.0.0.1. If using a self-signed certificate, you must use a valid certificate for production

6. "SSL certificate error" / Certificate verification failed

• Problem: Self-signed or invalid SSL certificate on the server
• Solution: Use a valid SSL certificate from a trusted Certificate Authority. Self-signed certificates are not supported in production environments

7. "No calendars found" / "No address books found"

• Problem: Authentication succeeded but no resources are available
• Solution: Verify your account has CalDAV calendars or CardDAV address books configured. Check your permissions on the CalDAV/CardDAV server. Try accessing calendars/contacts via the server's web interface

8. Claude Desktop not showing tools / Tools not available

• Problem: MCP server not loaded or configuration error
• Solution: Restart Claude Desktop after changing the configuration file. Verify the configuration file path is correct for your OS. Ensure npx is available in your PATH. Review Claude Desktop logs for error messages

9. "Cannot find module" / Module resolution error

• Problem: Package not installed or build directory missing (when running from source)
• Solution: Use npx -y mcp-twake-dav (recommended) or, if running from source, run npm run build to compile TypeScript

10. Connection refused on localhost

• Problem: Development server not running or wrong port
• Solution: For development, ensure your CalDAV/CardDAV server is running on localhost. Verify the port number in DAV_URL (e.g., http://localhost:8080)

Development

For contributors working from source:

git clone https://github.com/mmaudet/mcp-twake-dav.git
cd mcp-twake-dav
npm install
npm run build    # compile TypeScript
npm test         # run unit/integration tests
npm run dev      # watch mode (auto-rebuild on file changes)

The server uses the MCP stdio transport and communicates via JSON-RPC on stdin/stdout.

E2E Tests

The project includes E2E tests that run against a real CalDAV/CardDAV server. These are excluded from the regular test suite and must be run separately with proper credentials.

Setup:

# Copy the example environment file
cp .env.e2e.example .env.e2e

# Edit .env.e2e with your test credentials
# Required: E2E_DAV_URL, E2E_DAV_USERNAME, E2E_DAV_PASSWORD

Running E2E tests:

# Load environment and run tests
source .env.e2e && npm run test:e2e

E2E Test Files:

| File | Description | |------|-------------| | tests/e2e/calendar-crud.e2e.ts | Calendar CRUD operations, ETag conflicts, recurring events | | tests/e2e/contact-crud.e2e.ts | Contact CRUD operations, ETag conflicts | | tests/e2e/alarm-management.e2e.ts | VALARM add/remove operations | | tests/e2e/recurring-events.e2e.ts | Single occurrence editing (RECURRENCE-ID, EXDATE) | | tests/e2e/invitations.e2e.ts | Invitation list/respond (requires 2 users) | | tests/e2e/availability.e2e.ts | Free/busy availability checks |

Note: Invitation tests require a secondary user (E2E_DAV_USERNAME_2, E2E_DAV_PASSWORD_2) to act as organizer. Tests are skipped gracefully if secondary user is not configured.

All E2E tests create objects with [E2E-TEST] prefix and clean up after each test.

Architecture

mcp-twake-dav is built with a layered architecture:

1. Configuration Layer - Zod-based environment variable validation with fail-fast behavior and HTTPS enforcement
2. Logging Layer - Pino logger configured for stderr output (prevents stdout contamination in MCP stdio transport)
3. CalDAV/CardDAV Client Layer - Dual tsdav clients for CalDAV and CardDAV with discovery, multi-method authentication (Basic, Bearer), and connection validation
4. Infrastructure Layer - Retry logic with exponential backoff and jitter, CTag-based caching for performance optimization
5. Service Layer - CalendarService and AddressBookService with resource fetching and caching management
6. Transformation Layer - iCal.js-based parsing of iCalendar and vCard formats, timezone normalization, RRULE expansion, parse-modify-serialize for updates
7. MCP Tool Layer - 20 MCP tools exposing calendar and contact read/write functionality with natural language support and tool annotations
8. Entry Point - MCP server initialization with stdio transport

Key design decisions:

• ESM modules with .js import extensions (required by MCP SDK)
• Passive cache design (services check isCollectionDirty, not cache-driven fetches)
• AI-friendly error formatting ("What went wrong" + "How to fix it" pattern)
• Parse-modify-serialize for updates (preserves VALARM, X-properties, ATTENDEE parameters)
• MCP tool annotations for AI clients (readOnlyHint, destructiveHint, openWorldHint)

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

See the LICENSE file for details.

Copyright (c) 2026 LINAGORA https://linagora.com

Contributing

Contributions are welcome! Please read our Contributing Guidelines for details on the development workflow, code style, and pull request process.

Support

For issues, questions, or feature requests, please open an issue on the GitHub repository.

For commercial support or inquiries, contact LINAGORA at https://linagora.com.