mcp-nextcloud-calendar

MCP Nextcloud Calendar

A Model Context Protocol (MCP) server for Nextcloud Calendar integration.

Features

Fetch calendars from Nextcloud
ADHD-friendly organization features
MCP protocol support (Streamable HTTP and Legacy HTTP+SSE)

Usage

Using with npx

The easiest way to use this package is with npx:

npx mcp-nextcloud-calendar

Installation

For development or local installation:

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

# Or install locally
npm install mcp-nextcloud-calendar

MCP Client Configuration

To use with an MCP client (like Claude), add this configuration to your MCP client settings:

{
  "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"
      }
    }
  }
}

Specifying a Version

You can pin to a specific version of the package:

{
  "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

The server uses these environment variables, with defaults where possible:

Variable	Description	Default	Required
PORT	Server port	3001	No
SERVER_NAME	MCP server identifier	nextcloud-calendar-server	No
NODE_ENV	Environment (development/production)	development	No
NEXTCLOUD_BASE_URL	Your Nextcloud server URL	-	Yes
NEXTCLOUD_USERNAME	Your Nextcloud username	-	Yes
NEXTCLOUD_APP_TOKEN	Your Nextcloud app token	-	Yes
KEEP_ALIVE_INTERVAL	Keep-alive interval (ms)	30000	No

Development Setup

For local development:

Clone the repository
Install dependencies:

npm install

Create a .env file in the project root:

cp .env.example .env

Edit the .env file with your Nextcloud credentials.

Getting a Nextcloud App Token

Log in to your Nextcloud instance
Go to Settings → Security → App Passwords
Create a new app password with a name like "MCP Calendar"
Copy the generated token to your .env file

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

/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 following MCP tools are registered and available to clients:

Calendar Management

Tool	Description	Parameters
`listCalendars`	Retrieves all accessible calendars	None
`createCalendar`	Creates a new calendar	`displayName` (required), `color` (optional), `category` (optional), `focusPriority` (optional)
`updateCalendar`	Updates an existing calendar	`id` (required), `displayName` (optional), `color` (optional), `category` (optional), `focusPriority` (optional)
`deleteCalendar`	Deletes a calendar	`id` (required)

⚠️ Permission Warning: The updateCalendar and deleteCalendar tools may require special permissions in your Nextcloud instance. Calendar operations are subject to Nextcloud's permission system.

Event Management

Tool	Description	Parameters
`listEvents`	Retrieves events for a calendar	`calendarId` (required), `start` (optional), `end` (optional)
`getEvent`	Gets a specific event	`calendarId` (required), `eventId` (required)
`createEvent`	Creates a new event	`calendarId` (required), `summary` (required), `start` (required), `end` (required), `description` (optional), `location` (optional)
`updateEvent`	Updates an existing event	`calendarId` (required), `eventId` (required), [plus any event properties to update]
`deleteEvent`	Deletes an event	`calendarId` (required), `eventId` (required)

Known Issues and Limitations

Note: This package is currently in early development (0.1.x). APIs and tools may change without notice in future releases.

The update and delete calendar operations may require specific permissions in your Nextcloud instance
Error handling for specific Nextcloud error codes is still being improved
Large calendars with many events may experience performance issues

Please report any issues on the GitHub repository.

License

ISC

mcp-nextcloud-calendar