How to Make Your AI Assistant Access Nextcloud Calendar

The Toolkit

1. TypingMind - Chat UI for AI models with plugin support

2. Nextcloud - Self-hosted productivity platform (OSS alternative to Google Workspace)

3. LLM Tools - OpenAI’s function calling feature that lets AIs trigger real actions

Before You Start: Get Your Nextcloud App Token

What’s an app token?

How to Create It

1. Log into Nextcloud
   Go to your-nextcloud.com and sign in.

2. Open Settings
   Click your profile picture → Settings → Security tab.

3. Generate App Password
   Under Devices & sessions:
• Type the name of your app, e.g. “Calendar Bridge” or “TypingMind” in the app name field
• Click Create new app password

4. Save the Token
   Copy the generated code (e.g., AbCdE-12345-FgHiJ). This is your NEXTCLOUD_TOKEN for the .env file later.

Step 1: Create Your Calendar Web Service

1. Accepts requests from the AI

2. Authenticates those requests

3. Fetches the relevant calendar data

4. Returns it in a format the AI can understand

1.1 Set Up Node.js Project

mkdir calendar-bridge && cd calendar-bridge
yarn init -y
yarn add express cors tsdav node-ical luxon lodash dotenv

• express: Web server framework

• cors: Handle cross-origin requests

• tsdav: Connect to Nextcloud’s CalDAV API

• node-ical: Parse calendar data

• luxon: Better date/time handling than native JavaScript

• lodash: Utilities for data manipulation

• dotenv: Load environment variables from a file

1.2 Create nextcloud.js

const { createDAVClient } = require('tsdav');
const ical = require('node-ical');
const { DateTime } = require('luxon');
const { flatten, orderBy } = require('lodash');

// Adapt to match the display names of your calendars.
const CALENDARS = ['Allgemein', 'Contact birthdays'];

// Helper functions
const formatCalDAVTime = (isoString) => {
  // Parse the ISO string with Luxon to handle any timezone format
  const dt = DateTime.fromISO(isoString);
  // Format to CalDAV compatible format (UTC)
  return dt.toUTC().toFormat("yyyyMMdd'T'HHmmss'Z'");
};

const formatHumanDate = (date, locale = 'en-US') => {
  // Use native toLocaleDateString with options for full weekday and padded numbers
  return date.toLocaleDateString(locale, {
    weekday: 'long',
    year: 'numeric',
    month: '2-digit',
    day: '2-digit'
  });
};

const formatHumanTime = (date, locale = 'en-US') => {
  return date.toLocaleTimeString(locale, { hour: '2-digit', minute: '2-digit' });
};

const extractDescription = (value, startDate) => {
  if (value['NEXTCLOUD-BC-FIELD-TYPE'] === 'BDAY') {
    const birthYear = parseInt(value['NEXTCLOUD-BC-YEAR']);
    // calculate age how old the person will be on the given date
    const age = startDate.getFullYear() - birthYear;
    return `turns ${age} years old`;
  }
  if (typeof value.description === 'string') {
    return value.description;
  }
  if (value.description && value.description.val) {
    return value.description.val;
  }
  return null;
};

const getEventsFromCalendar = (calendarObjects, calendarName, startDateISO, endDateISO, locale = 'en-US') => {
  const parsedEvents = calendarObjects.map(e => ical.sync.parseICS(e.data));

  // filter out all object values which are type `VEVENT`
  const events = [];
  parsedEvents.forEach(event => {
    const eventValues = Object.values(event);
    eventValues.forEach(value => {
      if (value.type === 'VEVENT') {
        if (!value.rrule) {
          const description = extractDescription(value, value.start);
          events.push({
            title: value.summary,
            ...(value.location ? { location: value.location } : undefined),
            date: formatHumanDate(value.start, locale),
            begin: formatHumanTime(value.start, locale),
            ...(value.datetype === 'date-time') ? { end: formatHumanTime(value.end, locale) } : undefined,
            calendar: calendarName,
            ...(description ? { description } : undefined),
          });
        } else {
          const startDT = DateTime.fromISO(startDateISO);
          const endDT = DateTime.fromISO(endDateISO);
          const dates = value.rrule.between(startDT.toJSDate(), endDT.toJSDate());
          
          const originalStartTime = DateTime.fromJSDate(value.start);
          const originalEndTime = DateTime.fromJSDate(value.end);
          
          const originalStartHour = originalStartTime.hour;
          const originalStartMinute = originalStartTime.minute;
          const originalEndHour = originalEndTime.hour;
          const originalEndMinute = originalEndTime.minute;
          
          dates.forEach(date => {
            const localZone = DateTime.local().zoneName;
            const recurDate = DateTime.fromJSDate(date).setZone(localZone);
            
            const startDT = recurDate.set({
              hour: originalStartHour,
              minute: originalStartMinute
            });
            
            const endDT = recurDate.set({
              hour: originalEndHour,
              minute: originalEndMinute
            });
            
            const adjustedEndDT = endDT < startDT ? endDT.plus({ days: 1 }) : endDT;
            
            const description = extractDescription(value, startDT.toJSDate());
            
            events.push({
              title: value.summary,
              ...(value.location ? { location: value.location } : undefined),
              date: formatHumanDate(startDT.toJSDate(), locale),
              begin: formatHumanTime(startDT.toJSDate(), locale),
              ...(value.datetype === 'date-time') ? { 
                end: formatHumanTime(adjustedEndDT.toJSDate(), locale) 
              } : undefined,
              calendar: calendarName,
              ...(description ? { description } : undefined),
            });
          });
        }
      }
    });
  });
  return events;
};

const getCalendarEvents = async (startDateISO, endDateISO, locale = 'en-US') => {
  const config = {
    serverUrl: process.env.NEXTCLOUD_URL,
    user: process.env.NEXTCLOUD_USER,
    token: process.env.NEXTCLOUD_TOKEN,
  };

  const client = await createDAVClient({
    serverUrl: config.serverUrl,
    credentials: {
      username: config.user,
      password: config.token,
    },
    authMethod: "Basic",
    defaultAccountType: "caldav",
  });

  const calendars = await client.fetchCalendars();

  // Adjust the calendar names to match your Nextcloud setup
  const relevantCalendarDisplayNames = CALENDARS;

  const relevantCalendars = calendars.filter(calendar => relevantCalendarDisplayNames.includes(calendar.displayName));

  const calendarObjectsForAllCalendars = await Promise.all(relevantCalendars.map(calendar => client.fetchCalendarObjects({ 
    calendar,
    filters: [
      {
        'comp-filter': {
          _attributes: { name: 'VCALENDAR' },
          'comp-filter': {
            _attributes: { name: 'VEVENT' },
            'time-range': {
              _attributes: {
                start: formatCalDAVTime(startDateISO),
                end: formatCalDAVTime(endDateISO),
              },
            },
          },
        },
      },
    ]
   })));
   
   const allEvents = flatten(calendarObjectsForAllCalendars.map((calendarObjects, index) => {
     // Find the corresponding calendar display name (some calendars might have been filtered out)
     const calendarDisplayName = relevantCalendars[index]?.displayName || 'Unknown Calendar';
     return getEventsFromCalendar(calendarObjects, calendarDisplayName, startDateISO, endDateISO, locale);
   }));

  return orderBy(allEvents, ['begin'], ['asc']);
};

module.exports = { getCalendarEvents };

1.3 Create server.js

require('dotenv').config();
const express = require('express');
const cors = require('cors');
const { getCalendarEvents } = require('./nextcloud');

// The origin for CORS. Change it to https://www.typingmind.com or
// the URL of your custom TypingMind instance when you deploy the app.
const ORIGIN = '*'

const corsConfig = {
  origin: ORIGIN,
  methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS', 'PATCH'],
  allowedHeaders: ['Content-Type', 'Authorization', 'X-Requested-With', 'Accept', 'Origin'],
  exposedHeaders: ['Content-Length'],
  credentials: true,
};

const app = express();
app.use(express.json());

// Updated CORS configuration
app.use(cors(corsConfig));

// Handle preflight requests explicitly
app.options('/get-calendar-events', cors(corsConfig));

// Auth middleware - skip for OPTIONS requests
app.use((req, res, next) => {
  // Skip auth check for OPTIONS requests
  if (req.method === 'OPTIONS') {
    return next();
  }
  
  const authHeader = req.headers.authorization;
  if (!authHeader?.startsWith('bearer ') || authHeader.split(' ')[1] !== process.env.API_TOKEN) {
    return res.status(401).json({ error: { message: 'Unauthorized: Invalid or missing API token' } });
  }
  next();
});

app.post('/get-calendar-events', async (req, res) => {
  try {
    const { from, to, locale = 'en-US' } = req.body;
    
    if (!from || !to) {
      return res.status(400).json({ 
        error: { message: 'Missing parameters: from and to dates are required' }
      });
    }
    
    const events = await getCalendarEvents(from, to, locale);
    return res.json(events);
  } catch (error) {
    console.error('Error processing request:', error);
    res.status(500).json({ 
      error: { message: `Server error: ${error.message}` }
    });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => console.log(`Server running on port ${PORT}`));

1.4 Add Environment File (.env)

NEXTCLOUD_URL=https://your-nextcloud.com/remote.php/dav/calendars/
NEXTCLOUD_USER=your_username
NEXTCLOUD_TOKEN=your_app_password_from_earlier
API_TOKEN=create_a_secure_random_string_for_typingmind

1.5 Run It Locally

"scripts": {  
  "dev": "node server.js",
  "start": "node server.js"
}

yarn dev

Step 2: Configure TypingMind Plugin

• What data the model needs to know about the function

• How to call our API

• How to format the response for the AI

{
    "uuid": "fd017c80-186e-4a49-a77e-ac1abb9cefc9",
    "id": "get_calendar_events",
    "emoji": "📅",
    "title": "Get Nextcloud Calendar Events",
    "overviewMarkdown": "## Get Calendar Events\n\nGet calendar events from your Nextcloud account using custom API",
    "openaiSpec": {
        "name": "get_calendar_events",
        "parameters": {
            "type": "object",
            "required": [
                "from",
                "to",
                "locale"
            ],
            "properties": {
                "from": {
                    "type": "string",
                    "description": "Must be an RFC3339 timestamp with mandatory time zone offset, for example, 2011-06-03T10:00:00-07:00, 2011-06-03T10:00:00Z."
                },
                "to": {
                    "type": "string",
                    "description": "Must be an RFC3339 timestamp with mandatory time zone offset, for example, 2011-06-03T10:00:00-07:00, 2011-06-03T10:00:00Z."
                },
                "locale": {
                    "type": "string",
                    "description": "ISO language code for formatting dates and times, for example, 'en-US', 'de-DE', 'fr-FR'."
                }
            }
        },
        "description": "Return events in the user's Nextcloud calendar within a specific time range formatted according to the specified locale."
    },
    "userSettings": [
        {
            "name": "apiKey",
            "label": "API Key",
            "type": "password"
        },
        {
            "name": "apiUrl",
            "label": "API Route",
            "type": "text"
        }
    ],
    "code": "const makeRequest = async (url, method = 'GET', headers = {}, body) => {\n  try {\n    const options = {\n      method,\n      headers: {\n        'Content-Type': 'application/json',\n        ...headers\n      },\n      ...(body && { body: JSON.stringify(body) })\n    };\n\n    const response = await fetch(url, options);\n\n    if (!response.ok) {\n      const errorResponse = await response.json();\n      throw new Error(errorResponse.error?.message || 'Something went wrong');\n    }\n\n    return await response.json();\n  } catch (error) {\n    throw new Error(error.message || 'Unknown API error');\n  }\n};\n\nasync function get_calendar_events(params, userSettings) {\n  const { from, to, locale } = params;\n  const { apiKey, apiUrl } = userSettings;\n\n  const result = await makeRequest(\n    apiUrl,\n    'POST',\n    { 'Authorization': `bearer ${apiKey}` },\n    { from, to, locale }\n  );\n\n  return result;\n}\n",
    "syncedAt": null,
    "authenticationType": "AUTH_TYPE_NONE",
    "implementationType": "javascript",
    "oauthConfig": null,
    "outputType": "respond_to_ai"
}

1. The API Token you created in your .env file

2. The full URL to your calendar API endpoint (e.g., http://localhost:3000/get-calendar-events for local testing)

Step 3: Deploy Your Service (Optional)

• Railway: Simple deployment with GitHub integration

• Render: Free tier for small projects

• Fly.io: Distributed hosting with generous free tier

• Digital Ocean App Platform: More robust but paid option

1. Set all environment variables (NEXTCLOUD_URL, NEXTCLOUD_USER, NEXTCLOUD_TOKEN, API_TOKEN)

2. Enable HTTPS (critical for security!)

3. Update the API URL in your TypingMind plugin settings to point to your deployed service

Step 4: Talk to Your Calendar!

1. Determine time range needed

2. Call your Nextcloud plugin

3. Summarize the results in natural language

Why This Matters

Troubleshooting

• “NetworkError when attempting to fetch resource”: Check if your server is accessible from the internet and CORS is configured correctly

• “Unauthorized”: Verify the API key matches in the plugin settings and your .env file

• Calendar shows no data: Ensure your calendar names match the ones in nextcloud.js

• Time zone issues: Calendar events might show in wrong times if server and Nextcloud time zones differ