Skip to content
Back to search

mcp-ical

A Model Context Protocol Server that allows you to interact with your MacOS Calendar through natural language.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/omar-v2--mcp-ical/badge.svg)](/listings/omar-v2--mcp-ical)

HTML

<a href="/listings/omar-v2--mcp-ical"><img src="/api/listings/omar-v2--mcp-ical/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

> πŸ’‘ **Note**: While these instructions focus on setting up the MCP server with Claude for Desktop, this server can be used with any MCP-compatible client. For more details on using different clients, see [the MCP documentation](https://modelcontextprotocol.io/quickstart/client).

Prerequisites

- [uv package manager](https://github.com/astral-sh/uv) - macOS with Calendar app configured - An MCP client - [Claude for desktop](https://claude.ai/download) is recommended

Installation

Whilst this MCP server can be used with any MCP compatible client, the instructions below are for use with Claude for desktop.

1. **Clone and Setup**

```bash # Clone the repository git clone https://github.com/Omar-V2/mcp-ical.git cd mcp-ical

# Install dependencies uv sync ```

2. **Configure Claude for Desktop**

Create or edit `~/Library/Application\ Support/Claude/claude_desktop_config.json`:

```json { "mcpServers": { "mcp-ical": { "command": "uv", "args": [ "--directory", "/ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp-ical", "run", "mcp-ical" ] } } } ```

3. **Launch Claude for Calendar Access**

> ⚠️ **Critical**: Claude must be launched from the terminal to properly request calendar permissions. Launching directly from Finder will not trigger the permissions prompt.

Run the following command in your terminal.

```bash /Applications/Claude.app/Contents/MacOS/Claude ```

> ⚠️ **Warning**: Alternatively, you can [manually grant calendar access](docs/install.md#method-2-manually-grant-calendar-access), but this involves modifying system files and should only be done if you understand the risks involved.

4. **Start Using!**

```text Try: "What's my schedule looking like for next week?" ```

> πŸ”‘ **Note**: When you first use a calendar-related command, macOS will prompt for calendar access. This prompt will only appear if you launched Claude from the terminal as specified above.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md Β· README Β· 206 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # MCP iCal Server
  2. <div align="center">
  3. πŸ—“οΈ Natural Language Calendar Management for macOS
  4. [![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](https://choosealicense.com/licenses/mit/)
  5. [![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
  6. [![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-purple.svg)](https://modelcontextprotocol.io)
  7. </div>
  8. ## 🌟 Overview
  9. Transform how you interact with your macOS calendar using natural language! The mcp-ical server leverages the Model Context Protocol (MCP) to turn your calendar management into a conversational experience.
  10. ```bash
  11. You: "What's my schedule for next week?"
  12. Claude: "Let me check that for you..."
  13. [Displays a clean overview of your upcoming week]
  14. You: "Add a lunch meeting with Sarah tomorrow at noon"
  15. Claude: "✨ πŸ“… Created: Lunch with Sarah Tomorrow, 12:00 PM"
  16. ```
  17. ## ✨ Features
  18. ### πŸ“… Event Creation
  19. Transform natural language into calendar events instantly!
  20. ```text
  21. "Schedule a team lunch next Thursday at 1 PM at Bistro Garden"
  22. ↓
  23. πŸ“Ž Created: Team Lunch
  24. πŸ“… Thursday, 1:00 PM
  25. πŸ“ Bistro Garden
  26. ```
  27. #### Supported Features
  28. - Custom calendar selection
  29. - Location and notes
  30. - Smart reminders
  31. - Recurring events
  32. #### Power User Examples
  33. ```text
  34. πŸ”„ Recurring Events:
  35. "Set up my weekly team sync every Monday at 9 AM with a 15-minute reminder"
  36. πŸ“ Detailed Events:
  37. "Schedule a product review meeting tomorrow from 2-4 PM in the Engineering calendar,
  38. add notes about reviewing Q1 metrics, and remind me 1 hour before"
  39. πŸ“± Multi-Calendar Support:
  40. "Add a dentist appointment to my Personal calendar for next Wednesday at 3 PM"
  41. ```
  42. ### πŸ” Smart Schedule Management & Availability
  43. Quick access to your schedule with natural queries:
  44. ```text
  45. "What's on my calendar for next week?"
  46. ↓
  47. πŸ“Š Shows your upcoming events with smart formatting
  48. "When am I free to schedule a 2-hour meeting next Tuesday?"
  49. ↓
  50. πŸ•’ Available time slots found:
  51. β€’ Tuesday 10:00 AM - 12:00 PM
  52. β€’ Tuesday 2:00 PM - 4:00 PM
  53. ```
  54. ### ✏️ Intelligent Event Updates
  55. Modify events naturally:
  56. ```text
  57. Before: "Move tomorrow's team meeting to 3 PM instead"
  58. ↓
  59. After: ✨ Meeting rescheduled to 3:00 PM
  60. ```
  61. #### Update Capabilities
  62. - Time and date modifications
  63. - Calendar transfers
  64. - Location updates
  65. - Note additions
  66. - Reminder adjustments
  67. - Recurring pattern changes
  68. ### πŸ“Š Calendar Management
  69. - View all available calendars
  70. - Smart calendar suggestions
  71. - Seamless Google Calendar integration when configured with iCloud
  72. > πŸ’‘ **Pro Tip**: Since you can create events in custom calendars, if you have your Google Calendar synced with your iCloud Calendar, you can use this MCP server to create events in your Google Calendar too! Just specify the Google calendar when creating/updating events.
  73. ## πŸš€ Quick Start
  74. > πŸ’‘ **Note**: While these instructions focus on setting up the MCP server with Claude for Desktop, this server can be used with any MCP-compatible client. For more details on using different clients, see [the MCP documentation](https://modelcontextprotocol.io/quickstart/client).
  75. ### Prerequisites
  76. - [uv package manager](https://github.com/astral-sh/uv)
  77. - macOS with Calendar app configured
  78. - An MCP client - [Claude for desktop](https://claude.ai/download) is recommended
  79. ### Installation
  80. Whilst this MCP server can be used with any MCP compatible client, the instructions below are for use with Claude for desktop.
  81. 1. **Clone and Setup**
  82. ```bash
  83. # Clone the repository
  84. git clone https://github.com/Omar-V2/mcp-ical.git
  85. cd mcp-ical
  86. # Install dependencies
  87. uv sync
  88. ```
  89. 2. **Configure Claude for Desktop**
  90. Create or edit `~/Library/Application\ Support/Claude/claude_desktop_config.json`:
  91. ```json
  92. {
  93. "mcpServers": {
  94. "mcp-ical": {
  95. "command": "uv",
  96. "args": [
  97. "--directory",
  98. "/ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp-ical",
  99. "run",
  100. "mcp-ical"
  101. ]
  102. }
  103. }
  104. }
  105. ```
  106. 3. **Launch Claude for Calendar Access**
  107. > ⚠️ **Critical**: Claude must be launched from the terminal to properly request calendar permissions. Launching directly from Finder will not trigger the permissions prompt.
  108. Run the following command in your terminal.
  109. ```bash
  110. /Applications/Claude.app/Contents/MacOS/Claude
  111. ```
  112. > ⚠️ **Warning**: Alternatively, you can [manually grant calendar access](docs/install.md#method-2-manually-grant-calendar-access), but this involves modifying system files and should only be done if you understand the risks involved.
  113. 4. **Start Using!**
  114. ```text
  115. Try: "What's my schedule looking like for next week?"
  116. ```
  117. > πŸ”‘ **Note**: When you first use a calendar-related command, macOS will prompt for calendar access. This prompt will only appear if you launched Claude from the terminal as specified above.
  118. ## πŸ§ͺ Testing
  119. > ⚠️ **Warning**: Tests will create temporary calendars and events. While cleanup is automatic, only run tests in development environments.
  120. ```bash
  121. # Install dev dependencies
  122. uv sync --dev
  123. # Run test suite
  124. uv run pytest tests
  125. ```
  126. ## πŸ› Known Issues
  127. ### Recurring Events
  128. - Non-standard recurring schedules may not always be set correctly
  129. - Better results with Claude 3.5 Sonnet compared to Haiku
  130. - Reminder timing for recurring all-day events may be off by one day
  131. ## 🀝 Contributing
  132. Feedback and contributions are welcome. Here's how you can help:
  133. 1. Fork the repository
  134. 2. Create your feature branch
  135. 3. Commit your changes
  136. 4. Push to the branch
  137. 5. Open a Pull Request
  138. ## πŸ“ License
  139. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  140. ## πŸ™ Acknowledgments
  141. - Built with [Model Context Protocol](https://modelcontextprotocol.io)
  142. - macOS Calendar integration built with [PyObjC](https://github.com/ronaldoussoren/pyobjc)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.