MCP Nextcloud Calendar

You run an MCP server that connects to Nextcloud Calendar to fetch calendars and manage events through a single, standardized interface. This lets you expose Nextcloud calendars to MCP clients and automate tasks like listing calendars, creating and updating events, and syncing changes in real time.

How to use

You use an MCP client to connect to the Nextcloud Calendar MCP server. Start the server in the environment where your MCP ecosystem runs, then configure your MCP client to point at the server and supply your Nextcloud credentials. The server supports two transport modes for MCP clients: a streamable HTTP endpoint and legacy HTTP+SSE endpoints. You can perform common calendar operations such as listing calendars, creating and updating calendars, and managing events through the available MCP tools.

How to install

Prerequisites: have Node.js and npm installed on your machine.

1. Install the MCP server package globally or locally.

# Install globally
npm install -g mcp-nextcloud-calendar

# Or install locally
npm install mcp-nextcloud-calendar

Additional setup for MCP clients

Configure your MCP client to connect to the Nextcloud Calendar MCP server by providing the appropriate mcpServers configuration. The client should run the MCP command to start the server with the required environment variables.

{
  "mcpServers": {
    "nextcloud-calendar": {
      "command": "npx",
      "args": ["-y", "mcp-nextcloud-calendar"],
      "env": {
        "NEXTCLOUD_BASE_URL": "https://your-nextcloud-server.com",
        "NEXTCLOUD_USERNAME": "your-username",
        "NEXTCLOUD_APP_TOKEN": "your-app-token"
      }
    }
  }
}

Pin a specific version

If you want to lock to a particular package version, specify it in the MCP client configuration.

{
  "mcpServers": {
    "nextcloud-calendar": {
      "command": "npx",
      "args": ["-y", "mcp-nextcloud-calendar@0.1.0"],
      "env": {
        "NEXTCLOUD_BASE_URL": "https://your-nextcloud-server.com",
        "NEXTCLOUD_USERNAME": "your-username",
        "NEXTCLOUD_APP_TOKEN": "your-app-token"
      }
    }
  }
}

Configuration

Environment variables control how the server connects to Nextcloud and how it runs. The following variables are supported, with sensible defaults where noted.

PORT=3001
SERVER_NAME=nextcloud-calendar-server
NODE_ENV=development
NEXTCLOUD_BASE_URL=https://your-nextcloud-server.com
NEXTCLOUD_USERNAME=your-username
NEXTCLOUD_APP_TOKEN=your-app-token
KEEP_ALIVE_INTERVAL=30000

Development setup

For local development, follow these steps to prepare and run the server.

# Dependency installation
npm install

# Create a local environment file
cp .env.example .env

# Edit the .env file with your Nextcloud credentials

Getting a Nextcloud App Token

Create an app password in Nextcloud to grant the MCP server access. Use a name like “MCP Calendar” and copy the generated token into your environment file.

Development commands

Use these commands to build, run, test, and format the project during development.

# Build the project
npm run build

# Run in development mode
npm run dev

# Run tests
npm run test

# Run linting
npm run lint

# Format code
npm run format

API Endpoints

The MCP server exposes endpoints to manage calendars and fetch calendar data from Nextcloud.

• /mcp: Primary MCP endpoint (Streamable HTTP transport)

• /sse and /messages: Legacy MCP endpoints (HTTP+SSE transport)

• GET /health: Health check endpoint

• GET /api/calendars: List all calendars

MCP Tools

The server provides tools to manage calendars and events. Use these through the MCP interface to perform operations against your Nextcloud calendars.

Known issues and limitations

This MCP server is in early development (0.1.x). APIs and tools may change in future releases.

• Update and delete calendar operations may require specific permissions in Nextcloud.

• Error handling for certain Nextcloud error codes is still improving.

• Large calendars with many events may experience performance issues.

Report issues on the project’s issue tracker.

License

ISC license.

Available tools

listCalendars

Retrieves all accessible calendars

createCalendar

Creates a new calendar with a display name and optional color, category, and focus priority

updateCalendar

Updates an existing calendar with optional display name, color, category, and focus priority

deleteCalendar

Deletes a calendar by id

listEvents

Retrieves events for a calendar with optional start and end ranges

getEvent

Gets a specific event by calendar and event ID

createEvent

Creates a new event with required calendarId, summary, start, and end, plus optional description and location

updateEvent

Updates an existing event with calendarId, eventId, and updated properties

deleteEvent

Deletes an event by calendarId and eventId