Novacal MCP

Manage your Novacal calendar from your AI client — browse event types, check availability, and book, reschedule, or cancel events.

GitHub

Documentation

Novacal MCP Server

Minimal Cloudflare Worker that exposes a Novacal MCP server over Streamable HTTP with a simple hosted OAuth flow.

Users connect to the MCP server with OAuth, then paste their Novacal API key once on the Worker-hosted /authorize page. The key is encrypted into the OAuth session props, so it is only recoverable with the user's access token and is never stored in readable form.

MVP tools

  • novacal_get_event_types
  • novacal_get_event_type
  • novacal_create_event_type
  • novacal_get_availability
  • novacal_get_events
  • novacal_create_event
  • novacal_cancel_event
  • novacal_reschedule_event

Event type scope

novacal_get_event_types accepts an optional scope:

{
  "scope": "personal"
}

Use personal for the authenticated account owner's event types and team for team event types. Omit scope to return both.

Availability date ranges

novacal_get_availability accepts start and end as YYYY-MM-DD dates.

The range is start-inclusive and end-exclusive:

[start 00:00, end 00:00)

For a single day, pass the next calendar day as end.

Examples:

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

This returns availability for May 29, 2026.

Do not use the same value for start and end when asking for one day. For example, start=2026-05-29 and end=2026-05-29 is an empty range and returns no slots.

timezone is optional and defaults to UTC. When provided, use an IANA timezone such as Europe/Amsterdam, America/New_York, or Asia/Tokyo.

Environment variables

  • NOVACAL_API_BASE_URL - defaults to https://api.novacal.io

Cloudflare resources

Create these once:

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

Then copy the returned IDs into wrangler.toml for:

  • OAUTH_KV
  • DB

Apply the D1 schema:

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

The user_credentials table is legacy. Credentials now live in the encrypted OAuth session, and nothing reads or writes this table — it and the DB binding are kept only so existing deployments keep validating.

Local development

npm install
npm run dev

The MCP endpoint is available at http://127.0.0.1:8787/mcp.

The OAuth authorize page is at http://127.0.0.1:8787/authorize.

Deploy

npm run deploy

This deploys the production Wrangler environment.

Connection flow

  1. Add the remote MCP URL in your client:
    • local: http://127.0.0.1:8787/mcp
    • deployed: https://<your-worker-url>/mcp
  2. Use OAuth / remote auth in the MCP client.
  3. On first connect, the Worker sends you to /authorize.
  4. Paste your Novacal API key.
  5. The Worker verifies it with GET /v1/users/me, encrypts it into the OAuth session, and completes the flow.

to inspect locally, run: npx @modelcontextprotocol/inspector