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", "[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