novacal-mcp-server

Novacal 用のリモート MCP サーバーです。AI クライアントに8つのツールを提供し、イベントタイプの確認、空き状況の確認、ミーティングの予約、日程変更、キャンセルができます。

単一の Cloudflare Worker として動作し、Streamable HTTP を使用します。OAuth で一度接続し、Novacal API キーを貼り付ければ、その後はクライアントを使い続けられます。

---

接続

ホストされているサーバーの URL は https://mcp.novacal.io/mcp です。

Claude Code

claude mcp add --transport http novacal https://mcp.novacal.io/mcp

Cursor、Windsurf、または MCP 設定ファイルを使用するクライアント

{
  "mcpServers": {
    "novacal": {
      "type": "http",
      "url": "https://mcp.novacal.io/mcp"
    }
  }
}

Claude Desktop と claude.ai

カスタムコネクターを追加し、同じ URL を貼り付けます。

初回接続時に、クライアントでサインインページが開きます。Novacal API キーを貼り付けて「Connect」を押してください。セットアップはこれで完了です。

---

ツール

ツール	機能	引数
novacal_get_event_types	アカウントのイベントタイプを一覧表示	scope（personal または team、任意）
novacal_get_event_type	1つのイベントタイプを取得	id
novacal_create_event_type	イベントタイプを作成	name、slug、type、duration、hidden_from_profile、color + 任意のフィールド10個
novacal_get_availability	日付範囲内のイベントタイプの空き枠	event_type_id、start、end、timezone（任意）
novacal_get_events	アカウントのイベントを一覧表示	なし
novacal_create_event	イベントを予約	event_type_id、start、end、timezone、time_format、location、form_field_answers（任意）
novacal_cancel_event	予定されているイベントをキャンセル	id、cancellation_reason（任意）
novacal_reschedule_event	予定されているイベントの日程を変更	id、start、end、timezone、time_format、user_role、form_field_answers（任意）

読み取りツールは読み取り専用かつ冪等としてマークされています。novacal_cancel_event は破壊的操作としてマークされているため、破壊的な呼び出しの前に確認を求めるクライアントでは確認が行われます。

イベントタイプの範囲

novacal_get_event_types では、任意の scope を指定できます。

{ "scope": "personal" }

自分のイベントタイプには personal、チームのイベントタイプには team を指定します。どちらも取得する場合は省略してください。チームのイベントタイプを求められない限り、personal を優先するようサーバーがモデルに指示します。

空き状況の日付範囲

start と end は、YYYY-MM-DD 形式の日付です。範囲は 開始日を含み、終了日を含みません。

[start 00:00, end 00:00)

1日分を指定するには、end に翌日を渡します。

{
  "event_type_id": 123,
  "start": "2026-05-29",
  "end": "2026-05-30",
  "timezone": "Europe/Amsterdam"
}

これにより、2026年5月29日の空き状況が返されます。start と end に同じ日付を渡すと、範囲が空になり、何も返されません。

タイムゾーン

timezone には、Europe/Amsterdam、America/New_York、Asia/Tokyo などの IANA 名を指定します。省略した場合は UTC が既定値になります。

接続時に、サーバーは Novacal プロフィールのタイムゾーンを読み取り、サーバーの指示に設定します。そのため、モデルは相対日付をあなたのタイムゾーンで読み取り、別のタイムゾーンを指定しない限り、あなたのタイムゾーンで時刻を表示します。

---

認証の仕組み

1. クライアントが Worker に対して OAuth フローを開始します。
2. Worker が /authorize を提供し、Novacal API キーを求めます。
3. GET /v1/users/me でキーを検証します。
4. キーを OAuth セッションの props に暗号化して保存し、フローを完了します。

キーを復元できるのは、あなたのアクセストークンを使った場合のみです。読み取り可能な形式でストレージに書き込まれることはなく、ページに表示されることもありません。また、暗号化されずに保存される grant メタデータにも含まれません。

クライアントで接続を解除しても、キーは無効になりません。アクセスを遮断するには、Novacal でキーをローテーションしてください。

---

ローカル開発

デプロイには Node 20 以降と Cloudflare アカウントが必要です。

npm install
npm run dev

エンドポイント	URL
MCP	http://127.0.0.1:8787/mcp
サインインページ	http://127.0.0.1:8787/authorize
ヘルスチェック	http://127.0.0.1:8787/health

npm run dev は dev Wrangler 環境を使用します。KV と D1 をローカルでシミュレートし、http://localhost:8010 の Novacal API に接続するため、本番リソースには一切触れません。

ツールを手動で試すには、次のようにします。

npx @modelcontextprotocol/inspector

チェック

npm run check    # tsc --noEmit
npm run lint     # biome check
npm run format   # biome check --write
npm test         # vitest run

CI は、すべてのプッシュとプルリクエストで、Node 20 を使用して check、lint、test を実行します。

---

デプロイ

Cloudflare リソースを一度作成します。

npx wrangler kv namespace create OAUTH_KV
npx wrangler d1 create novacal-mcp-server-db

返された ID を wrangler.toml の OAUTH_KV と DB にコピーしてから、スキーマを適用します。

npx wrangler d1 execute novacal-mcp-server-db --remote --file=./migrations/0001_user_credentials.sql

production 環境をデプロイします。

npm run deploy

注記： user_credentials テーブルはレガシーです。現在、認証情報は暗号化された OAuth セッションに保存され、このテーブルの読み書きは行われません。既存のデプロイで検証が引き続き成功するように、このテーブルと DB バインディングを残しています。

設定

名前	種類	値
NOVACAL_API_BASE_URL	var	本番環境では https://api.novacal.io、開発環境では http://localhost:8010
OAUTH_KV	KV namespace	OAuth クライアント、grant、トークンのストレージ
DB	D1 database	レガシー、未使用

---

構成

src/
├── index.ts            OAuthProvider wiring, /authorize, metadata routes
├── auth.ts             API key verification and the sign-in page
├── mcp.ts              tool registration and server instructions
├── api.ts              Novacal HTTP client, UpstreamApiError, 30s timeout
├── responses.ts        okResult / failedResult envelopes
├── types.ts            Env, session props, Novacal types
└── handlers/
    ├── event-types.ts  list, get, create
    ├── events.ts       list, create, cancel, reschedule
    └── availability.ts availability lookup

ハンドラーは MCP のインポートを必要としない通常の async 関数なので、単独で簡単にテストできます。各ツールはハンドラーを try/catch で囲み、例外をスローする代わりに isError の結果を返します。エラーは生の JSON ダンプではなく、短いヒントとしてモデルに伝わります。

401 — Novacal API key is invalid or revoked. Re-authorize at /authorize.
429 — Rate limited by the Novacal API. Wait a moment before retrying.

Novacal API への呼び出しは 30 秒後にタイムアウトします。

公開ルート

ルート	目的
GET /	サーバー名とステータス
GET /health	ヘルスチェック
GET /.well-known/oauth-protected-resource	/mcp サフィックスのバリエーションを含む RFC 9728 メタデータ
GET POST /authorize	サインインページとフォーム送信
POST /token, POST /register	OAuthProvider が処理
POST /mcp	MCP エンドポイント。ベアラートークンが必要

---

リンク

• Novacal
• Model Context Protocol
• MCP レジストリエントリー — io.github.ste7/novacal-mcp-server