What is Mcp Nextcloud Calendar

mcp-nextcloud-calendar is a Model Context Protocol (MCP) server designed for integration with Nextcloud Calendar, allowing users to manage and fetch calendars seamlessly.

Use cases

Use cases include personal calendar management, team scheduling, and integration with other applications that require calendar data from Nextcloud.

How to use

To use mcp-nextcloud-calendar, clone the repository, install dependencies using ‘npm install’, and configure your Nextcloud credentials in the ‘.env’ file. After setup, you can run the server and access the API endpoints for calendar management.

Key features

Key features include fetching calendars from Nextcloud, ADHD-friendly organization features, and support for the MCP protocol.

Where to use

mcp-nextcloud-calendar can be used in personal productivity applications, team collaboration tools, and any environment requiring calendar integration with Nextcloud.

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:

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