README.md•5.29 kB
# MCP Nextcloud Calendar
[](https://www.npmjs.com/package/mcp-nextcloud-calendar)
[](https://opensource.org/licenses/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:
```bash
npx mcp-nextcloud-calendar
```
### Installation
For development or local installation:
```bash
# 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:
```json
{
"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:
```json
{
"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:
| 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:
```bash
npm install
```
3. Create a `.env` file in the project root:
```bash
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
```bash
# 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
[](https://ko-fi.com/cheffromspace)