MCP Calender Agent

🚀 iCal Server Based on MCP

This project is an implementation of an iCal server based on the MCP protocol. Its main functions include creating, querying, and managing calendar events. Compared with the original implementation, this project adopts a brand - new architectural design, uses an OpenAI agent to handle natural language requests, and simplifies client integration.

🚀 Quick Start

This iCal server based on the MCP protocol offers a seamless solution for calendar event management. With its intelligent design and user - friendly features, it simplifies the process of interacting with calendars.

✨ Features

• Single - Point Access: All calendar operations can be completed with just one MCP tool.
• Intelligent Agent: It has a built - in OpenAI agent that parses natural language requests and translates them into specific operation instructions.
• Context Awareness: It supports session - level context tracking to enhance the interaction experience.
• Simplified Integration: Clients only need to call one tool, reducing the integration complexity.

📦 Installation

Environment Requirements

• Python 3.8 or higher
• An OpenAI account and API Key
• macOS system (due to the dependency on PyObjC)

Installation Steps

# Clone the repository
git clone https://github.com/yourusername/mcp-ical.git
cd mcp-ical

# Install dependencies
pip install openai pyobjc

💻 Usage Examples

Basic Usage

1. Configure the OpenAI API Key:

   • Create or edit the configuration file config.json.
   • Add the following content:

     {
         "openai_api_key": "your-api-key-here"
     }
     

2. Start the service:

   uv run mcp-ical
   

3. Example usage:

   Send a request: "/ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp-ical" mcp-ical
   

📚 Documentation

Core Components

1. CalendarAgent

   • It is responsible for parsing natural language instructions and generating corresponding operations.
   • Implemented using OpenAI's Agent SDK.
   • Supports multiple interaction methods: text, voice, etc.

2. EventManager

   • Handles specific calendar operations, such as creating, updating, and deleting events.
   • Integrates with the macOS system's calendar service.
   • Provides detailed logging and error handling.

🔧 Technical Details

Request Flow

Client -> CalendarAgent -> EventManager -> System Calendar

Core Dependencies

• OpenAI SDK: Used to implement the intelligent agent function.
• PyObjC: Used to interact with the macOS system's calendar service.

Known Issues

Recurring Event Issues

• Non - standard recurring patterns may not be set correctly.
• A more powerful LLM model can improve the effect.
• The reminder time for all - day recurring events may be offset by one day.

🤝 How to Contribute

Any form of feedback and contribution is welcome. Please follow these steps:

1. Fork this repository to your account.
2. Create a feature branch (e.g., feature/new - feature).
3. Commit your changes.
4. Push the branch to the remote repository.
5. Submit a Pull Request to the main branch.

📄 License

This project is licensed under the MIT License. Please refer to the LICENSE file for details.

🙏 Acknowledgments

• Original Project: Based on Omar - V2's mcp - ical.
• Protocol Support: Uses Model Context Protocol.
• Calendar Integration: Depends on PyObjC.
• Intelligent Agent: Supported by OpenAI Agent SDK.