davmcp – "DAVx⁵ for AI"

An experimental Model Context Protocol (MCP) server for CalDAV access.

It allows AI models to connect to CalDAV (in the future maybe also CardDAV and WebDAV) servers and run various queries like "list events" or "create event". For you as a user of such a model, it means that you can use natural language to manage your calendars, for instance: "Add a two-hour event tomorrow from 1 pm with title: 'Some Appointment'", and the AI model can directly add the event to the calendar over CalDAV.

The CalDAV server credentials stay in davmcp all the time and are not exposed to the AI model.

The Model Context Protocol is a protocol for AI agents to interact with external tools and services in a structured way.

⚠️ Experimental Status

Warning

This project is experimental and under active development. The API and functionality may change without notice. There are no automatic database migrations.

Caution

Not intended for production use. Only use in test environments.

There's no UI for configuration yet. You'll have to add database entries manually to make it work.

What it does

davmcp provides calendar management capabilities through the Model Context Protocol. It acts as a bridge between MCP clients and CalDAV servers, enabling AI agents and other MCP-compatible tools to manage calendar events.

• CalDAV Integration: Connects to standard CalDAV calendar servers
• TODO: CardDAV integration
• TODO: WebDAV integration
• Events CRUD Operations: Create, read, update, and delete calendar events
• TODO: CRUD for contacts, tasks, journal entries
• TODO: provide access to WebDAV resources
• Auxiliary tools: Query current time and time-based information (needed because LLMs don't have a concept of time)

Quick Start

These are the steps to manually compile and run davmcp. You can also use Docker instead.

1. Prepare the required environment: Currently only a JDK is needed. sqlite3 or a similar tool is required to edit the database since there's no configuration UI (yet). npx (NodeJS package manager) is needed if you want to run the MCP Inspector.

2. Check out or download davmcp.

3. Change the directory to the server subproject and keep using that directory for all remaining commands in this section and in Configuration:

   cd server

4. Build the server:

   ../gradlew :server:build

5. Create a database directory and run the server:

   mkdir -p data && ../gradlew :server:run --args="3000"

   (Replace 3000 with your desired port)

   Alternatively, you can build a fat JAR (see Development) and run it from server with java -jar build/libs/server-*-all.jar 3000.

   The server will start and listen for MCP connections on the specified port.

   The MCP path is /mcp, so you can access it at http://localhost:3000/mcp (or any other of your IP addresses because the server listens on 0.0.0.0).

   If that works, hit Ctrl+C to shut the server down. It should have created a database file named data/users.db.

Configuration

All commands in this section assume your current working directory is still server.

1. Add user and access token:

   The AI that acts on your behalf has to authenticate against davmcp. You have to create a token for that in the database:

   sqlite3 data/users.db "INSERT INTO user (name, email) VALUES ('Your Name', 'your-email@example.com');"
   # first user has now user id=1
   
   # use a random string for <your-access-token>   
   sqlite3 data/users.db "INSERT INTO accessToken (userId, token) VALUES (1, '<your-access-token>');"

   That token is later required when you connect the AI to davmcp.

2. Add CalDAV service and calendars:

   # Only use test accounts because davmcp is experimental.
   # The service credentials are stored in davmcp and won't be exposed to the AI model.
   sqlite3 data/users.db "INSERT INTO service (userId, username, password, baseUrl) VALUES (1, 'your-caldav-username', 'your-caldav-password', 'https://caldav.example.com');"
   # first service now has service id=1
   
   sqlite3 data/users.db "INSERT INTO collection (serviceId, url, displayName) VALUES (1, 'https://caldav.example.com/calendars/user/calendar1', 'My Calendar');"
   sqlite3 data/users.db "INSERT INTO collection (serviceId, url, displayName) VALUES (1, 'https://caldav.example.com/calendars/user/calendar2', 'My Second Calendar');"

3. Optional: Verify MCP is working.

   • Access http://localhost:3000/mcp with your browser. It should show 401 Unauthorized because no access token is sent.
   • You can verify that the MCP is working using the MCP inspector: from another terminal, change to server as well, run npx @modelcontextprotocol/inspector, and then connect to http://localhost:3000/mcp, using a Custom Header for authentication (Authorization: Bearer <your-access-token>). Once you're connected, you can List Tools and try out whatever tool you like.

4. Add the MCP connection to your AI model.

   How this step is done depends on the used environment. Look in the documentation of your AI environment for how to add an MCP server.

   • If you use a command-line interface (CLI) to the model, you can usually add an MCP server in the configuration file. Use http://localhost:3000/mcp as MCP URL in that case. Configure authentication with token so that the CLI sends Authorization: Bearer <your-access-token>.
   • When you run a model locally, you can usually also add MCP servers somehow.
   • If you use a cloud model (usually over a Web interface or an API), you have to run the MCP server on a public URL because the remote model needs access to it. You can run the davmcp server behind a reverse proxy like nginx ( configure for SSE!) and then configure the public URL, usually something like https://your-public-server.com/mcp in the model configuration. Again, set the authentication method to token and provide your access token. Alternatively, add Authorization: Bearer <your-access-token> to the headers.

5. Enable the MCP/tools for specific requests.

   You may have to enable the MCP or its tools when you send a request to the model. For instance, if you're using a remote model over a Web interface, you may need to click some "+" button and select the davmcp server to allow its usage in the request.

   Example request you can try: "Which events do I have in my calendar this week?"

Development

This project uses Gradle for dependency management and building:

# Build a fat JAR with all dependencies
cd server
../gradlew :server:fatJar

# Run tests
../gradlew :server:test