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:

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

> ⚠️ 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

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