# iCal MCP Server

A modern Model Context Protocol (MCP) server for managing iCalendar files. This server allows AI assistants to interact with calendar data through a standardized protocol.

## Features

- **Load calendars** from:
  - Local files (`.ics`)
  - HTTP/HTTPS URLs
- **Query events** with filters for:
  - Date ranges
  - Search text (summary, description, location)
  - Location
  - Recurring event expansion
- **Full CRUD operations**:
  - Create new events
  - Update existing events
  - Delete events
- **Multiple calendar support**: Load and manage multiple calendars simultaneously
- **Read-only mode**: HTTP calendars are automatically read-only

## Installation

### Using npx (recommended)

You can run the server directly without installation:

```bash
npx @jonas/ical-mcp
```

### Global Installation

```bash
npm install -g @jonas/ical-mcp
ical-mcp
```

### Local Development

```bash
git clone https://github.com/jnss95/ical-mcp.git
cd ical-mcp
npm install
npm run build
npm start
```

## Configuration

### Environment Variables

Calendars are configured using environment variables at startup:

| Variable | Description |
|----------|-------------|
| `CALENDAR_LINK` | URL or path to a calendar (id defaults to "default") |
| `CALENDAR_LINK_{id}` | URL or path to a calendar with custom id |

**Examples:**

Single calendar (id defaults to "default"):
```bash
CALENDAR_LINK=https://example.com/calendar.ics
```

Multiple calendars with custom IDs:
```bash
CALENDAR_LINK_work=https://example.com/work.ics
CALENDAR_LINK_personal=/path/to/personal.ics
CALENDAR_LINK_holidays=https://example.com/holidays.ics
```

### VS Code MCP Configuration

Add to your VS Code settings (`.vscode/mcp.json`):

```json
{
  "servers": {
    "ical": {
      "type": "stdio",
      "command": "npx",
      "args": ["@jnss95/ical-mcp"],
      "env": {
        "CALENDAR_LINK": "https://example.com/your-calendar.ics"
      }
    }
  }
}
```

With multiple calendars:

```json
{
  "servers": {
    "ical": {
      "type": "stdio",
      "command": "npx",
      "args": ["@jnss95/ical-mcp"],
      "env": {
        "CALENDAR_LINK_work": "https://example.com/work.ics",
        "CALENDAR_LINK_personal": "/path/to/personal.ics"
      }
    }
  }
}
```

### Claude Desktop Configuration

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "ical": {
      "command": "npx",
      "args": ["@jnss95/ical-mcp"],
      "env": {
        "CALENDAR_LINK": "https://example.com/your-calendar.ics"
      }
    }
  }
}
```

## Available Tools

### Calendar Management

| Tool | Description |
|------|-------------|
| `list_calendars` | List all loaded calendars |
| `get_calendar_info` | Get metadata about a loaded calendar |

### Event Operations

| Tool | Description |
|------|-------------|
| `list_events` | List all events in a calendar |
| `search_events` | Search events with filters |
| `get_event` | Get details of a specific event |
| `create_event` | Create a new event |
| `update_event` | Update an existing event |
| `delete_event` | Delete an event |

## Tool Examples

### List Calendars

```json
{
  "tool": "list_calendars",
  "arguments": {}
}
```

### Search Events

```json
{
  "tool": "search_events",
  "arguments": {
    "calendarId": "work",
    "startDate": "2024-01-01T00:00:00Z",
    "endDate": "2024-01-31T23:59:59Z",
    "searchText": "meeting",
    "expandRecurring": true
  }
}
```

### Create Event

```json
{
  "tool": "create_event",
  "arguments": {
    "calendarId": "work",
    "summary": "Team Meeting",
    "start": "2024-01-15T10:00:00Z",
    "end": "2024-01-15T11:00:00Z",
    "description": "Weekly team sync",
    "location": "Conference Room A"
  }
}
```

### Create Recurring Event

```json
{
  "tool": "create_event",
  "arguments": {
    "calendarId": "work",
    "summary": "Daily Standup",
    "start": "2024-01-15T09:00:00Z",
    "end": "2024-01-15T09:15:00Z",
    "rrule": "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR"
  }
}
```

### Update Event

```json
{
  "tool": "update_event",
  "arguments": {
    "calendarId": "work",
    "eventId": "event-uid@example.com",
    "summary": "Updated Meeting Title",
    "location": "New Location"
  }
}
```

## Development

### Running Tests

```bash
# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch
```

### Building

```bash
# Build TypeScript
npm run build

# Watch mode
npm run watch
```

## Project Structure

```
ical_mcp/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── calendar/
│   │   ├── calendar.ts       # Calendar class (CRUD operations)
│   │   ├── loader.ts         # Calendar loading utilities
│   │   └── index.ts          # Module exports
│   └── types/
│       ├── calendar.ts       # Type definitions
│       ├── ical.d.ts         # ical.js type declarations
│       └── index.ts          # Type exports
├── build/                    # Compiled JavaScript
├── package.json
├── tsconfig.json
└── vitest.config.ts
```

## License

MIT