MCP Nextcloud Calendar

MCP Nextcloud Calendar

Nextcloud Calendar と連携する Model Context Protocol（MCP）サーバーです。

特長

• Nextcloud からカレンダーを取得します
• ADHD に配慮した整理機能を備えています
• MCP プロトコルに対応しています（Streamable HTTP および Legacy HTTP+SSE）

使い方

npx を使用する

このパッケージを使う最も簡単な方法は、npx を使用することです。

npx mcp-nextcloud-calendar

インストール

開発またはローカルへのインストールの場合：

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

# Or install locally
npm install mcp-nextcloud-calendar

MCP クライアントの設定

MCP クライアント（Claude など）で使用するには、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"
      }
    }
  }
}

バージョンの指定

パッケージの特定のバージョンを固定できます。

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

設定

環境変数

サーバーでは次の環境変数を使用します。可能な場合はデフォルト値が設定されています。

変数	説明	デフォルト	必須
PORT	サーバーのポート	3001	いいえ
SERVER_NAME	MCP サーバーの識別子	nextcloud-calendar-server	いいえ
NODE_ENV	環境（development/production）	development	いいえ
NEXTCLOUD_BASE_URL	お使いの Nextcloud サーバーの URL	-	はい
NEXTCLOUD_USERNAME	お使いの Nextcloud ユーザー名	-	はい
NEXTCLOUD_APP_TOKEN	お使いの Nextcloud アプリトークン	-	はい
KEEP_ALIVE_INTERVAL	キープアライブ間隔（ms）	30000	いいえ

開発環境のセットアップ

ローカルで開発する場合：

1. リポジトリをクローンします
2. 依存関係をインストールします。

npm install

3. プロジェクトのルートに .env ファイルを作成します。

cp .env.example .env

4. .env ファイルに Nextcloud の認証情報を入力します。

Nextcloud アプリトークンの取得

1. Nextcloud インスタンスにログインします
2. 「設定」→「セキュリティ」→「アプリパスワード」に移動します
3. 「MCP Calendar」などの名前を付けて、新しいアプリパスワードを作成します
4. 生成されたトークンを .env ファイルにコピーします

開発

# 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

API エンドポイント

• /mcp - 主要な MCP エンドポイント（Streamable HTTP トランスポート）
• /sse および /messages - 従来の MCP エンドポイント（HTTP+SSE トランスポート）
• GET /health - ヘルスチェックエンドポイント
• GET /api/calendars - すべてのカレンダーを一覧表示します

MCP ツール

次の MCP ツールが登録されており、クライアントから利用できます。

カレンダー管理

ツール	説明	パラメーター
listCalendars	アクセス可能なすべてのカレンダーを取得します	なし
createCalendar	新しいカレンダーを作成します	displayName（必須）、color（任意）、category（任意）、focusPriority（任意）
updateCalendar	既存のカレンダーを更新します	id（必須）、displayName（任意）、color（任意）、category（任意）、focusPriority（任意）
deleteCalendar	カレンダーを削除します	id（必須）

⚠️ 権限に関する警告：updateCalendar および deleteCalendar ツールの使用には、Nextcloud インスタンスで特別な権限が必要な場合があります。カレンダーの操作には Nextcloud の権限システムが適用されます。

イベント管理

ツール	説明	パラメーター
listEvents	カレンダーのイベントを取得します	calendarId（必須）、start（任意）、end（任意）
getEvent	特定のイベントを取得します	calendarId（必須）、eventId（必須）
createEvent	新しいイベントを作成します	calendarId（必須）、summary（必須）、start（必須）、end（必須）、description（任意）、location（任意）
updateEvent	既存のイベントを更新します	calendarId（必須）、eventId（必須）、［更新するイベントプロパティを指定］
deleteEvent	イベントを削除します	calendarId（必須）、eventId（必須）

既知の問題と制限事項

注記：このパッケージは現在、初期開発段階（0.1.x）です。今後のリリースで、API やツールが予告なく変更される場合があります。

• カレンダーの更新操作および削除操作には、Nextcloud インスタンスで特定の権限が必要な場合があります
• Nextcloud の特定のエラーコードに対するエラーハンドリングは、現在も改善中です
• イベントが多数ある大規模なカレンダーでは、パフォーマンスの問題が発生する場合があります

問題が発生した場合は、GitHub リポジトリでご報告ください。

ライセンス

ISC