novacal-mcp-server

# 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`:

```json
{
  "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**:

```txt
[start 00:00, end 00:00)
```

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

Examples:

```json
{
  "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:

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

Then copy the returned IDs into [wrangler.toml](/Users/stefanbabic/Sites/personal/events/mcp-server/wrangler.toml) for:

- `OAUTH_KV`
- `DB`

Apply the D1 schema:

```bash
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

```bash
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

```bash
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