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