# novacal-mcp-server [Health: Active] **Category:** 💻 Developer Tools **Repository:** https://github.com/ste7/novacal-mcp-server **GitHub Stars:** 0 **Views:** 0 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/novacal-mcp-server ## Description Manage Novacal event types, availability, and bookings. ## Claude Desktop Quick Installation Install path detected from listing signals. Uses `npx` (confidence: high): ```json "mcpServers": { "novacal-mcp-server": { "command": "npx", "args": ["-y","@modelcontextprotocol/inspector"] } } ``` ## Documentation & README Novacal MCP Server [![CI status](https://shieldcn.dev/github/ci/ste7/novacal-mcp-server.svg?variant=secondary&workflow=CI&branch=main)](https://github.com/ste7/novacal-mcp-server/actions/workflows/ci.yml) [![Transport: Streamable HTTP](https://shieldcn.dev/badge/transport-Streamable%20HTTP-blue.svg?variant=secondary&logo=modelcontextprotocol)](https://modelcontextprotocol.io) [![Tools: 8](https://shieldcn.dev/badge/tools-8-blue.svg?variant=secondary)](#tools) [![Deploys to Cloudflare Workers](https://shieldcn.dev/badge/deploys%20to-Cloudflare%20Workers-orange.svg?variant=secondary&logo=cloudflare)](https://workers.cloudflare.com) [![Last commit](https://shieldcn.dev/github/last-commit/ste7/novacal-mcp-server.svg?variant=secondary)](https://github.com/ste7/novacal-mcp-server/commits/main) A remote [MCP](https://modelcontextprotocol.io) server for [Novacal](https://novacal.io). 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** ```bash claude mcp add --transport http novacal https://mcp.novacal.io/mcp ``` **Cursor, Windsurf, or any client with an MCP config file** ```json { "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 | Tool | What it does | Arguments | | --- | --- | --- | | `novacal_get_event_types` | List event types on the account | `scope` (`personal` or `team`, optional) | | `novacal_get_event_type` | Fetch one event type | `id` | | `novacal_create_event_type` | Create an event type | `name`, `slug`, `type`, `duration`, `hidden_from_profile`, `color` + 10 optional fields | | `novacal_get_availability` | Free slots for an event type in a date range | `event_type_id`, `start`, `end`, `timezone` (optional) | | `novacal_get_events` | List events on the account | none | | `novacal_create_event` | Book an event | `event_type_id`, `start`, `end`, `timezone`, `time_format`, `location` and `form_field_answers` (optional) | | `novacal_cancel_event` | Cancel a future event | `id`, `cancellation_reason` (optional) | | `novacal_reschedule_event` | Move a future event | `id`, `start`, `end`, `timezone`, `time_format`, `user_role` and `form_field_answers` (optional) | 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`: ```json { "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**: ```txt [start 00:00, end 00:00) ``` For a single day, pass the next day as `end`: ```json { "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. ```bash npm install npm run dev ``` | Endpoint | URL | | --- | --- | | MCP | `http://127.0.0.1:8787/mcp` | | Sign-in page | `http://127.0.0.1:8787/authorize` | | Health check | `http://127.0.0.1:8787/health` | `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: ```bash npx @modelcontextprotocol/inspector ``` ### Checks ```bash 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: ```bash npx wrangler kv namespace create OAUTH_KV npx wrangler d1 create novacal-mcp-server-db ``` Copy the returned IDs into [wrangler.toml](https://github.com/ste7/novacal-mcp-server/blob/HEAD/wrangler.toml) under `OAUTH_KV` and `DB`, then apply the schema: ```bash npx wrangler d1 execute novacal-mcp-server-db --remote --file=./migrations/0001_user_credentials.sql ``` Deploy the `production` environment: ```bash 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 | Name | Type | Value | | --- | --- | --- | | `NOVACAL_API_BASE_URL` | var | `https://api.novacal.io` in production, `http://localhost:8010` in dev | | `OAUTH_KV` | KV namespace | OAuth client, grant, and token storage | | `DB` | D1 database | legacy, unused | --- ## How it is put together ```txt 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: ```txt 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 | Route | Purpose | | --- | --- | | `GET /` | server name and status | | `GET /health` | health check | | `GET /.well-known/oauth-protected-resource` | RFC 9728 metadata, with `/mcp` suffix variant | | `GET POST /authorize` | sign-in page and form post | | `POST /token`, `POST /register` | handled by OAuthProvider | | `POST /mcp` | the MCP endpoint, requires a bearer token | --- ## Links - [Novacal](https://novacal.io) - [Model Context Protocol](https://modelcontextprotocol.io) - [MCP registry entry](https://registry.modelcontextprotocol.io) — `io.github.ste7/novacal-mcp-server`