Servidor MCP Nextcloud Calendar | Awesome MCP Servers

MCP Nextcloud Calendar

Um servidor Model Context Protocol (MCP) para integração com o Nextcloud Calendar.

Recursos

Buscar calendários do Nextcloud
Recursos de organização amigáveis para TDAH
Suporte ao protocolo MCP (Streamable HTTP e Legacy HTTP+SSE)

Uso

Usando com npx

A maneira mais fácil de usar este pacote é com npx:

npx mcp-nextcloud-calendar

Instalação

Para desenvolvimento ou instalação local:

# Install globally
npm install -g mcp-nextcloud-calendar

# Or install locally
npm install mcp-nextcloud-calendar

Configuração do Cliente MCP

Para usar com um cliente MCP (como o Claude), adicione esta configuração às configurações do seu cliente MCP:

{
  "mcpServers": {
    "nextcloud-calendar": {
      "command": "npx",
      "args": ["-y", "mcp-nextcloud-calendar"],
      "env": {
        "NEXTCLOUD_BASE_URL": "https://your-nextcloud-server.com",
        "NEXTCLOUD_USERNAME": "your-username",
        "NEXTCLOUD_APP_TOKEN": "your-app-token"
      }
    }
  }
}

Especificando uma Versão

Você pode fixar uma versão específica do pacote:

{
  "mcpServers": {
    "nextcloud-calendar": {
      "command": "npx",
      "args": ["-y", "mcp-nextcloud-calendar@0.1.0"],
      "env": {
        "NEXTCLOUD_BASE_URL": "https://your-nextcloud-server.com",
        "NEXTCLOUD_USERNAME": "your-username",
        "NEXTCLOUD_APP_TOKEN": "your-app-token"
      }
    }
  }
}

Configuração

Variáveis de Ambiente

O servidor usa estas variáveis de ambiente, com padrões quando possível:

Variável	Descrição	Padrão	Obrigatório
PORT	Porta do servidor	3001	Não
SERVER_NAME	Identificador do servidor MCP	nextcloud-calendar-server	Não
NODE_ENV	Ambiente (desenvolvimento/produção)	development	Não
NEXTCLOUD_BASE_URL	URL do seu servidor Nextcloud	-	Sim
NEXTCLOUD_USERNAME	Seu nome de usuário do Nextcloud	-	Sim
NEXTCLOUD_APP_TOKEN	Seu token de aplicativo do Nextcloud	-	Sim
KEEP_ALIVE_INTERVAL	Intervalo de keep-alive (ms)	30000	Não

Configuração de Desenvolvimento

Para desenvolvimento local:

Clone o repositório
Instale as dependências:

npm install

Crie um arquivo .env na raiz do projeto:

cp .env.example .env

Edite o arquivo .env com suas credenciais do Nextcloud.

Obtendo um Token de Aplicativo do Nextcloud

Faça login na sua instância do Nextcloud
Vá em Configurações → Segurança → Senhas de aplicativos
Crie uma nova senha de aplicativo com um nome como "MCP Calendar"
Copie o token gerado para o seu arquivo .env

Desenvolvimento

# Build the project
npm run build

# Run in development mode
npm run dev

# Run tests
npm run test

# Run linting
npm run lint

# Format code
npm run format

Endpoints da API

/mcp - Endpoint MCP principal (transporte Streamable HTTP)
/sse e /messages - Endpoints MCP legados (transporte HTTP+SSE)
GET /health - Endpoint de verificação de saúde
GET /api/calendars - Lista todos os calendários

Ferramentas MCP

As seguintes ferramentas MCP estão registradas e disponíveis para os clientes:

Gerenciamento de Calendários

Ferramenta	Descrição	Parâmetros
`listCalendars`	Recupera todos os calendários acessíveis	Nenhum
`createCalendar`	Cria um novo calendário	`displayName` (obrigatório), `color` (opcional), `category` (opcional), `focusPriority` (opcional)
`updateCalendar`	Atualiza um calendário existente	`id` (obrigatório), `displayName` (opcional), `color` (opcional), `category` (opcional), `focusPriority` (opcional)
`deleteCalendar`	Exclui um calendário	`id` (obrigatório)

⚠️ Aviso de Permissão: As ferramentas updateCalendar e deleteCalendar podem exigir permissões especiais na sua instância do Nextcloud. As operações de calendário estão sujeitas ao sistema de permissões do Nextcloud.

Gerenciamento de Eventos

Ferramenta	Descrição	Parâmetros
`listEvents`	Recupera eventos de um calendário	`calendarId` (obrigatório), `start` (opcional), `end` (opcional)
`getEvent`	Obtém um evento específico	`calendarId` (obrigatório), `eventId` (obrigatório)
`createEvent`	Cria um novo evento	`calendarId` (obrigatório), `summary` (obrigatório), `start` (obrigatório), `end` (obrigatório), `description` (opcional), `location` (opcional)
`updateEvent`	Atualiza um evento existente	`calendarId` (obrigatório), `eventId` (obrigatório), [mais quaisquer propriedades do evento a serem atualizadas]
`deleteEvent`	Exclui um evento	`calendarId` (obrigatório), `eventId` (obrigatório)

Problemas e Limitações Conhecidos

Nota: Este pacote está atualmente em desenvolvimento inicial (0.1.x). APIs e ferramentas podem mudar sem aviso prévio em versões futuras.

As operações de atualização e exclusão de calendários podem exigir permissões específicas na sua instância do Nextcloud
O tratamento de erros para códigos de erro específicos do Nextcloud ainda está sendo melhorado
Calendários grandes com muitos eventos podem apresentar problemas de desempenho

Por favor, relate quaisquer problemas no repositório do GitHub.

Licença

ISC

Nextcloud Calendar

Documentação