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)

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

License

ISC

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

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.