npm package: @foxychat-mcp/apple-calendar
Description: Model Context Protocol (MCP) server for Apple Calendar integration
Author: FoxyChat MCP
Latest version: 0.0.2

# Apple Calendar MCP Server

Model Context Protocol (MCP) server for Apple Calendar integration. Create events, read calendar events, search events, delete events, get today's events, and manage calendars using AppleScript.

## Features

- 🚀 **Built on reliable MCP patterns** from mcp-starter-template
- 🛠️ **TypeScript with strict typing** and Zod validation
- 🔧 **AppleScript integration** for native macOS Calendar access
- ⚡ **Delimiter-based parsing** to avoid JSON errors
- 🎯 **Retry mechanisms** and comprehensive error handling
- 📅 **6 powerful calendar tools** for complete calendar management
- 📚 **Resource endpoints** for calendars and today's events

## Available Tools

### `get_calendars`
Get list of all calendars in the Calendar app.

**Parameters:** None

### `get_calendar_events`
Get events from a specific calendar within a date range.

**Parameters:**
- `calendar_name` (string): Name of the calendar to read events from
- `days_range` (number, optional): Number of days to look ahead (default: 7)

### `create_event`
Create a new calendar event.

**Parameters:**
- `calendar_name` (string): Name of the calendar to create event in
- `summary` (string): Event title/summary
- `start_date` (string): Start date and time (ISO format)
- `end_date` (string): End date and time (ISO format)
- `location` (string, optional): Event location
- `description` (string, optional): Event description
- `all_day` (boolean, optional): Whether this is an all-day event

### `search_events`
Search for events by title/summary across all calendars.

**Parameters:**
- `query` (string): Search query to match event titles
- `days_range` (number, optional): Number of days to search (default: 30)

### `get_today_events`
Get all events for today from all calendars.

**Parameters:** None

### `delete_event`
Delete an event by summary and date.

**Parameters:**
- `calendar_name` (string): Name of the calendar containing the event
- `event_summary` (string): Title/summary of the event to delete
- `event_date` (string): Start date of the event (ISO format)

## Resources

### `calendar://calendars`
JSON resource containing all available calendars.

### `calendar://today`
JSON resource containing all events for today.

## Quick Start

1. **Install dependencies**:
   ```bash
   npm install
   ```

2. **Build the server**:
   ```bash
   npm run build
   ```

3. **Test the server**:
   ```bash
   echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node dist/main.js
   ```

4. **Add to Claude Desktop config**:
   ```json
   {
     "mcpServers": {
       "apple-calendar": {
         "command": "node",
         "args": ["/Users/your-username/mcp/Remote-MCP-Servers/apple-calendar/dist/main.js"]
       }
     }
   }
   ```

5. **Grant permissions**:
   - Open **System Settings** → **Privacy & Security** → **Privacy**
   - Select **"Full Disk Access"**
   - Add and enable **Claude Desktop**
   - Restart Claude Desktop

## Development

### Adding New Tools

1. Create tool directory: `src/tools/your_tool/`
2. Add schema file: `src/tools/your_tool/schema.ts`
3. Add implementation: `src/tools/your_tool/index.ts`
4. Register in `src/tools/index.ts`

### Technical Implementation

This server features:
- **AppleScript Integration**: Native Calendar app access via `osascript`
- **Delimiter-based Parsing**: Uses `|||` and `:::` delimiters to avoid JSON parsing errors
- **Retry Mechanisms**: Automatic retry with exponential backoff for reliability
- **Type Safety**: Full TypeScript typing with Zod schema validation
- **Error Handling**: Comprehensive error catching and user-friendly messages

### Scripts

```bash
npm run build      # Build for production
npm run start      # Start the server (after build)
npm run clean      # Clean build directory
npm run check      # Lint and format code
npm run test       # Run tests
```

## Troubleshooting

### "Server failed to start"
- Check build output: `npm run build`
- Verify file permissions: `chmod +x dist/main.js`
- Check Claude Desktop config syntax

### "Permission denied"
- Ensure Claude Desktop has Full Disk Access permission
- Restart Claude Desktop after permission changes

### "Calendar not found"
- Use `get_calendars` tool to see available calendar names
- Calendar names are case-sensitive and must match exactly

## License

MIT

## Contributing

This MCP server was generated using the `init-mcp.md` workflow from the MCP Development Workflows, integrating existing Apple Calendar MCP code into the mcp-starter-template structure.

Refer to `/Users/7yank/mcp/Remote-MCP-Servers/MCP_DEVELOPMENT_GUIDE.md` for detailed development patterns and best practices.

---

**🎉 Your Apple Calendar MCP server is ready!**

Generated using the mcp-starter-template and integrated with existing Apple Calendar code through the FoxyChat MCP workflows.