Novacal MCP Server README

A remote MCP server for Novacal. It gives your AI client eight tools to read your event types, check availability, and book, reschedule, or cancel meetings.

It runs as a single Cloudflare Worker and speaks Streamable HTTP. You connect once with OAuth, paste your Novacal API key, and your client keeps working from there.

Connect

The hosted server is at https://mcp.novacal.io/mcp.

Claude Code

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

Cursor, Windsurf, or any client with an MCP config file

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

Claude Desktop and claude.ai

Add a custom connector and paste the same URL.

On first connect your client opens the sign-in page. Paste your Novacal API key and press Connect. That is the whole setup.

Tools

Read tools are marked read-only and idempotent. novacal_cancel_event is marked destructive, so clients that ask before destructive calls will ask.

Event type scope

novacal_get_event_types takes an optional scope:

{ "scope": "personal" }

Use personal for your own event types and team for team event types. Leave it out to get both. The server tells the model to prefer personal unless you ask for a team event type.

Availability date ranges

start and end are plain 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 day as end:

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

That returns availability for May 29, 2026. Passing the same date for start and end is an empty range and returns nothing.

Timezones

timezone takes an IANA name such as Europe/Amsterdam, America/New_York, or Asia/Tokyo. It defaults to UTC when omitted.

On connect the server reads your Novacal profile timezone and puts it in the server instructions. So the model reads relative dates in your timezone and shows times in your timezone, unless you ask for another one.

How auth works

1. Your client starts an OAuth flow against the Worker.
2. The Worker serves /authorize and asks for your Novacal API key.
3. It verifies the key with GET /v1/users/me.
4. It encrypts the key into the OAuth session props and completes the flow.

The key is only recoverable with your access token. It is never written to storage in readable form, never echoed back into the page, and is kept out of the grant metadata, which is stored unencrypted.

Removing the connection in your client does not revoke the key. To cut off access, rotate the key in Novacal.

Local development

You need Node 20+ and a Cloudflare account for deploys.

npm install
npm run dev

npm run dev uses the dev Wrangler environment. It simulates KV and D1 locally and points at a Novacal API on http://localhost:8010, so it never touches production resources.

To poke at the tools by hand:

npx @modelcontextprotocol/inspector

Checks

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

CI runs check, lint, and test on Node 20 for every push and pull request.

Deploy

Create the Cloudflare resources once:

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

Copy the returned IDs into wrangler.toml under OAUTH_KV and DB, then apply the schema:

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

Deploy the production environment:

npm run deploy

Note: 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 stay only so existing deployments keep validating.

Configuration

How it is put together

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

Handlers are plain async functions with no MCP imports, so they are easy to test on their own. Every tool wraps its handler in a try/catch and returns an isError result instead of throwing. Failures reach the model as a short hint, not a raw JSON dump:

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

Calls to the Novacal API time out after 30 seconds.

Public routes

Links

• Novacal
• Model Context Protocol
• MCP registry entry — io.github.ste7/novacal-mcp-server