CalDAV MCP

caldav-mcp

✨ Recursos

• Conectar a servidores CalDAV
• Listar calendários
• Listar eventos de calendário em um período específico
• Criar eventos de calendário
• Atualizar eventos de calendário
• Excluir eventos de calendário por UID

Configuração

{
  "mcpServers": {
    ...,
    "calendar": {
      "command": "npx",
      "args": [
        "caldav-mcp"
      ],
      "env": {
        "CALDAV_BASE_URL": "<CalDAV server URL>",
        "CALDAV_USERNAME": "<CalDAV username>",
        "CALDAV_PASSWORD": "<CalDAV password>"
      }
    }
  }
}

Desenvolvimento

Início Rápido

Execute o servidor MCP em modo de desenvolvimento com recarga automática:

npm run dev

Isso executará o código TypeScript diretamente com modo de observação e carregará automaticamente as variáveis de ambiente de .env.

Compilação Manual

Alternativamente, você pode compilar TypeScript para JavaScript e executá-lo:

1. Compile:

npx tsc

2. Execute:

node dist/index.js

Ferramentas Disponíveis

list-calendars

Lista todos os calendários retornando nome e URL

Parâmetros: nenhum

Retorna:

• Lista de todos os calendários disponíveis

list-events

Lista todos os eventos entre a data de início e a data de término no calendário especificado pela sua URL

Parâmetros:

• start: string — Data de início (ISO 8601)
• end: string — Data de término (ISO 8601)
• calendarUrl: string

Retorna:

• Uma lista de eventos que se enquadram no período fornecido, cada um contendo uid, summary, start, end e, opcionalmente, description e location

create-event

Cria um evento no calendário especificado pela sua URL. Para eventos de dia inteiro, defina wholeDay como true. Para um evento de dia inteiro de um único dia, use as datas e horas start e end na mesma data do calendário; elas não precisam ser timestamps idênticos.

Parâmetros:

• summary: string
• start: string — Data e hora de início (ISO 8601)
• end: string — Data e hora de término (ISO 8601)
• wholeDay: boolean (opcional) — Criar como evento de dia inteiro
• calendarUrl: string
• description: string (opcional)
• location: string (opcional)
• recurrenceRule: object (opcional)
  • freq: enum (DAILY | WEEKLY | MONTHLY | YEARLY) (opcional)
  • interval: number (opcional)
  • count: number (opcional)
  • until: string (opcional)
  • byday: array of string (opcional)
  • bymonthday: array of number (opcional)
  • bymonth: array of number (opcional)

Retorna:

• O ID único do evento criado

update-event

Atualiza um evento existente no calendário especificado pela sua URL. Apenas os campos fornecidos são alterados. Para um evento de dia inteiro de um dia, defina wholeDay como true e defina start e end para o mesmo dia do calendário.

Parâmetros:

• uid: string — Identificador único do evento a atualizar (obtido de list-events)
• calendarUrl: string
• summary: string (opcional)
• start: string (opcional)
• end: string (opcional)
• wholeDay: boolean (opcional) — Atualizar se este é um evento de dia inteiro
• description: string (opcional)
• location: string (opcional)
• recurrenceRule: object (opcional)
  • freq: enum (DAILY | WEEKLY | MONTHLY | YEARLY) (opcional)
  • interval: number (opcional)
  • count: number (opcional)
  • until: string (opcional)
  • byday: array of string (opcional)
  • bymonthday: array of number (opcional)
  • bymonth: array of number (opcional)

Retorna:

• O ID único do evento atualizado

delete-event

Exclui um evento no calendário especificado pela sua URL

Parâmetros:

• uid: string — Identificador único do evento a excluir (obtido de list-events)
• calendarUrl: string

Retorna:

• Mensagem de confirmação quando o evento é excluído com sucesso

list-todos

Lista tarefas (VTODOs) no calendário especificado pela sua URL. Por padrão, retorna apenas tarefas abertas (NEEDS-ACTION e IN-PROCESS), ordenadas por ordem manual e depois pela data de vencimento. Use status para incluir tarefas concluídas (COMPLETED) ou todas (ALL), e limit/offset para paginar listas longas.

Parâmetros:

• calendarUrl: string
• status: enum (OPEN | ALL | NEEDS-ACTION | COMPLETED | IN-PROCESS | CANCELLED) (opcional) — Filtrar por status. OPEN (padrão) = NEEDS-ACTION + IN-PROCESS; ALL = tudo; ou um status exato (NEEDS-ACTION, COMPLETED, IN-PROCESS, CANCELLED).
• due_before: string (opcional) — Somente tarefas com data de vencimento até esta (ISO 8601). Tarefas sem data são excluídas quando uma janela de vencimento é definida.
• due_after: string (opcional) — Somente tarefas com data de vencimento a partir desta (ISO 8601). Tarefas sem data são excluídas quando uma janela de vencimento é definida.
• limit: number (opcional) — Máximo de tarefas a retornar (padrão 50, máximo 500)
• offset: number (opcional) — Tarefas a pular (padrão 0)

Retorna:

• Um objeto { todos, total, limit, offset } onde total é a contagem antes da paginação. Cada tarefa tem uid, summary, status e, opcionalmente, due, start, completed, description, location.

create-todo

Cria uma tarefa (VTODO) no calendário especificado pela sua URL. Apenas summary é obrigatório; uma tarefa pode não ter datas. Use due para um prazo e start para quando o trabalho deve começar.

Parâmetros:

• summary: string
• calendarUrl: string
• due: string (opcional) — Data e hora de vencimento (ISO 8601)
• start: string (opcional) — Data e hora de início (ISO 8601)
• description: string (opcional)
• location: string (opcional)
• status: enum (NEEDS-ACTION | COMPLETED | IN-PROCESS | CANCELLED) (opcional) — Padrão é NEEDS-ACTION quando omitido

Retorna:

• O ID único da tarefa criada

update-todo

Atualiza uma tarefa existente (VTODO) no calendário especificado pela sua URL. Apenas os campos fornecidos são alterados. Para marcar uma tarefa como concluída, prefira a ferramenta complete-todo.

Parâmetros:

• uid: string — Identificador único da tarefa a atualizar (de list-todos)
• calendarUrl: string
• summary: string (opcional)
• due: string (opcional)
• start: string (opcional)
• description: string (opcional)
• location: string (opcional)
• status: enum (NEEDS-ACTION | COMPLETED | IN-PROCESS | CANCELLED) (opcional)

Retorna:

• O ID único da tarefa atualizada

complete-todo

Marca uma tarefa (VTODO) como concluída. Define seu status como COMPLETED e registra o horário de conclusão.

Parâmetros:

• uid: string — Identificador único da tarefa a concluir (de list-todos)
• calendarUrl: string

Retorna:

• O ID único da tarefa concluída

delete-todo

Exclui uma tarefa (VTODO) no calendário especificado pela sua URL

Parâmetros:

• uid: string — Identificador único da tarefa a excluir (de list-todos)
• calendarUrl: string

Retorna:

• Mensagem de confirmação quando a tarefa é excluída com sucesso

Licença

MIT