MCP iCal Server

Um servidor para realizar operações CRUD no aplicativo Calendário do macOS.

Documentação

Servidor MCP iCal

🗓️ Gerenciamento de Calendário por Linguagem Natural para macOS

🌟 Visão Geral

Transforme a forma como você interage com o calendário do macOS usando linguagem natural! O servidor mcp-ical utiliza o Model Context Protocol (MCP) para transformar o gerenciamento do seu calendário em uma experiência conversacional.

You: "What's my schedule for next week?"
Claude: "Let me check that for you..."
[Displays a clean overview of your upcoming week]

You: "Add a lunch meeting with Sarah tomorrow at noon"
Claude: "✨ 📅 Created: Lunch with Sarah Tomorrow, 12:00 PM"

✨ Recursos

📅 Criação de Eventos

Transforme linguagem natural em eventos de calendário instantaneamente!

"Schedule a team lunch next Thursday at 1 PM at Bistro Garden"
↓
📎 Created: Team Lunch
   📅 Thursday, 1:00 PM
   📍 Bistro Garden

Recursos Suportados

Seleção personalizada de calendário
Local e notas
Lembretes inteligentes
Eventos recorrentes

Exemplos para Usuários Avançados

🔄 Recurring Events:
"Set up my weekly team sync every Monday at 9 AM with a 15-minute reminder"

📝 Detailed Events:
"Schedule a product review meeting tomorrow from 2-4 PM in the Engineering calendar, 
add notes about reviewing Q1 metrics, and remind me 1 hour before"

📱 Multi-Calendar Support:
"Add a dentist appointment to my Personal calendar for next Wednesday at 3 PM"

🔍 Gerenciamento Inteligente de Agenda e Disponibilidade

Acesso rápido à sua agenda com consultas em linguagem natural:

"What's on my calendar for next week?"
↓
📊 Shows your upcoming events with smart formatting

"When am I free to schedule a 2-hour meeting next Tuesday?"
↓
🕒 Available time slots found:
   • Tuesday 10:00 AM - 12:00 PM
   • Tuesday 2:00 PM - 4:00 PM

✏️ Atualizações Inteligentes de Eventos

Modifique eventos naturalmente:

Before: "Move tomorrow's team meeting to 3 PM instead"
↓
After: ✨ Meeting rescheduled to 3:00 PM

Capacidades de Atualização

Modificações de horário e data
Transferências entre calendários
Atualizações de local
Adição de notas
Ajustes de lembretes
Alterações em padrões recorrentes

📊 Gerenciamento de Calendários

Visualizar todos os calendários disponíveis
Sugestões inteligentes de calendário
Integração perfeita com o Google Calendar quando configurado com o iCloud

💡 Dica Profissional: Como você pode criar eventos em calendários personalizados, se tiver seu Google Calendar sincronizado com o iCloud Calendar, você também pode usar este servidor MCP para criar eventos no seu Google Calendar! Basta especificar o calendário do Google ao criar/atualizar eventos.

🚀 Início Rápido

💡 Nota: Embora estas instruções foquem na configuração do servidor MCP com o Claude for Desktop, este servidor pode ser usado com qualquer cliente compatível com MCP. Para mais detalhes sobre o uso com diferentes clientes, consulte a documentação do MCP.

Pré-requisitos

Gerenciador de pacotes uv
macOS com o aplicativo Calendário configurado
Um cliente MCP - Claude for Desktop é recomendado

Instalação

Embora este servidor MCP possa ser usado com qualquer cliente compatível com MCP, as instruções abaixo são para uso com o Claude for Desktop.

Clonar e Configurar

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

# Install dependencies
uv sync

Configurar o Claude for Desktop

Crie ou edite ~/Library/Application\ Support/Claude/claude_desktop_config.json:

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

Iniciar o Claude para Acesso ao Calendário

⚠️ Crítico: O Claude deve ser iniciado pelo terminal para solicitar corretamente as permissões de calendário. Iniciar diretamente pelo Finder não acionará o prompt de permissões.

Execute o seguinte comando no seu terminal.
```
/Applications/Claude.app/Contents/MacOS/Claude
```
⚠️ Aviso: Alternativamente, você pode conceder acesso ao calendário manualmente, mas isso envolve modificar arquivos do sistema e só deve ser feito se você entender os riscos envolvidos.

Comece a Usar!

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

🔑 Nota: Ao usar um comando relacionado ao calendário pela primeira vez, o macOS solicitará acesso ao calendário. Este prompt só aparecerá se você tiver iniciado o Claude pelo terminal, conforme especificado acima.

🧪 Testes

⚠️ Aviso: Os testes criarão calendários e eventos temporários. Embora a limpeza seja automática, execute os testes apenas em ambientes de desenvolvimento.

# Install dev dependencies
uv sync --dev

# Run test suite
uv run pytest tests

🐛 Problemas Conhecidos

Eventos Recorrentes

Agendas recorrentes não padrão podem não ser configuradas corretamente em alguns casos
Melhores resultados com Claude 3.5 Sonnet em comparação com Haiku
O horário dos lembretes para eventos recorrentes de dia inteiro pode estar com um dia de diferença

🤝 Contribuições

Feedback e contribuições são bem-vindos. Veja como você pode ajudar:

Faça um fork do repositório
Crie sua branch de funcionalidade
Faça commit das suas alterações
Envie para a branch
Abra um Pull Request

📝 Licença

Este projeto está licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.

🙏 Agradecimentos

Construído com Model Context Protocol
Integração com o Calendário do macOS construída com PyObjC