Nextcloud Calendar

npm version License: ISC

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", "[email protected]"],
      "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:

1. Clone the repository
2. Install dependencies:

npm install

3. Create a .env file in the project root:

cp .env.example .env

4. Edit the .env file with your Nextcloud credentials.

Getting a Nextcloud App Token

1. Log in to your Nextcloud instance
2. Go to Settings → Security → App Passwords
3. Create a new app password with a name like "MCP Calendar"
4. 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

ko-fi