{ "markdown": "\n \n \"Novacal\n\n\n[![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)\n[![Transport: Streamable HTTP](https://shieldcn.dev/badge/transport-Streamable%20HTTP-blue.svg?variant=secondary&logo=modelcontextprotocol)](https://modelcontextprotocol.io)\n[![Tools: 8](https://shieldcn.dev/badge/tools-8-blue.svg?variant=secondary)](#tools)\n[![Deploys to Cloudflare Workers](https://shieldcn.dev/badge/deploys%20to-Cloudflare%20Workers-orange.svg?variant=secondary&logo=cloudflare)](https://workers.cloudflare.com)\n[![Last commit](https://shieldcn.dev/github/last-commit/ste7/novacal-mcp-server.svg?variant=secondary)](https://github.com/ste7/novacal-mcp-server/commits/main)\n\nA 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.\n\nIt 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.\n\n---\n\n## Connect\n\nThe hosted server is at `https://mcp.novacal.io/mcp`.\n\n**Claude Code**\n\n```bash\nclaude mcp add --transport http novacal https://mcp.novacal.io/mcp\n```\n\n**Cursor, Windsurf, or any client with an MCP config file**\n\n```json\n{\n \"mcpServers\": {\n \"novacal\": {\n \"type\": \"http\",\n \"url\": \"https://mcp.novacal.io/mcp\"\n }\n }\n}\n```\n\n**Claude Desktop and claude.ai**\n\nAdd a custom connector and paste the same URL.\n\nOn first connect your client opens the sign-in page. Paste your Novacal API key and press Connect. That is the whole setup.\n\n---\n\n## Tools\n\n| Tool | What it does | Arguments |\n| --- | --- | --- |\n| `novacal_get_event_types` | List event types on the account | `scope` (`personal` or `team`, optional) |\n| `novacal_get_event_type` | Fetch one event type | `id` |\n| `novacal_create_event_type` | Create an event type | `name`, `slug`, `type`, `duration`, `hidden_from_profile`, `color` + 10 optional fields |\n| `novacal_get_availability` | Free slots for an event type in a date range | `event_type_id`, `start`, `end`, `timezone` (optional) |\n| `novacal_get_events` | List events on the account | none |\n| `novacal_create_event` | Book an event | `event_type_id`, `start`, `end`, `timezone`, `time_format`, `location` and `form_field_answers` (optional) |\n| `novacal_cancel_event` | Cancel a future event | `id`, `cancellation_reason` (optional) |\n| `novacal_reschedule_event` | Move a future event | `id`, `start`, `end`, `timezone`, `time_format`, `user_role` and `form_field_answers` (optional) |\n\nRead tools are marked read-only and idempotent. `novacal_cancel_event` is marked destructive, so clients that ask before destructive calls will ask.\n\n### Event type scope\n\n`novacal_get_event_types` takes an optional `scope`:\n\n```json\n{ \"scope\": \"personal\" }\n```\n\nUse `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.\n\n### Availability date ranges\n\n`start` and `end` are plain `YYYY-MM-DD` dates. The range is **start-inclusive** and **end-exclusive**:\n\n```txt\n[start 00:00, end 00:00)\n```\n\nFor a single day, pass the next day as `end`:\n\n```json\n{\n \"event_type_id\": 123,\n \"start\": \"2026-05-29\",\n \"end\": \"2026-05-30\",\n \"timezone\": \"Europe/Amsterdam\"\n}\n```\n\nThat returns availability for May 29, 2026. Passing the same date for `start` and `end` is an empty range and returns nothing.\n\n### Timezones\n\n`timezone` takes an IANA name such as `Europe/Amsterdam`, `America/New_York`, or `Asia/Tokyo`. It defaults to `UTC` when omitted.\n\nOn 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.\n\n---\n\n## How auth works\n\n1. Your client starts an OAuth flow against the Worker.\n2. The Worker serves `/authorize` and asks for your Novacal API key.\n3. It verifies the key with `GET /v1/users/me`.\n4. It encrypts the key into the OAuth session props and completes the flow.\n\nThe 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.\n\nRemoving the connection in your client does not revoke the key. To cut off access, rotate the key in Novacal.\n\n---\n\n## Local development\n\nYou need Node 20+ and a Cloudflare account for deploys.\n\n```bash\nnpm install\nnpm run dev\n```\n\n| Endpoint | URL |\n| --- | --- |\n| MCP | `http://127.0.0.1:8787/mcp` |\n| Sign-in page | `http://127.0.0.1:8787/authorize` |\n| Health check | `http://127.0.0.1:8787/health` |\n\n`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.\n\nTo poke at the tools by hand:\n\n```bash\nnpx @modelcontextprotocol/inspector\n```\n\n### Checks\n\n```bash\nnpm run check # tsc --noEmit\nnpm run lint # biome check\nnpm run format # biome check --write\nnpm test # vitest run\n```\n\nCI runs `check`, `lint`, and `test` on Node 20 for every push and pull request.\n\n---\n\n## Deploy\n\nCreate the Cloudflare resources once:\n\n```bash\nnpx wrangler kv namespace create OAUTH_KV\nnpx wrangler d1 create novacal-mcp-server-db\n```\n\nCopy the returned IDs into [wrangler.toml](wrangler.toml) under `OAUTH_KV` and `DB`, then apply the schema:\n\n```bash\nnpx wrangler d1 execute novacal-mcp-server-db --remote --file=./migrations/0001_user_credentials.sql\n```\n\nDeploy the `production` environment:\n\n```bash\nnpm run deploy\n```\n\n> **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.\n\n### Configuration\n\n| Name | Type | Value |\n| --- | --- | --- |\n| `NOVACAL_API_BASE_URL` | var | `https://api.novacal.io` in production, `http://localhost:8010` in dev |\n| `OAUTH_KV` | KV namespace | OAuth client, grant, and token storage |\n| `DB` | D1 database | legacy, unused |\n\n---\n\n## How it is put together\n\n```txt\nsrc/\n├── index.ts OAuthProvider wiring, /authorize, metadata routes\n├── auth.ts API key verification and the sign-in page\n├── mcp.ts tool registration and server instructions\n├── api.ts Novacal HTTP client, UpstreamApiError, 30s timeout\n├── responses.ts okResult / failedResult envelopes\n├── types.ts Env, session props, Novacal types\n└── handlers/\n ├── event-types.ts list, get, create\n ├── events.ts list, create, cancel, reschedule\n └── availability.ts availability lookup\n```\n\nHandlers 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:\n\n```txt\n401 — Novacal API key is invalid or revoked. Re-authorize at /authorize.\n429 — Rate limited by the Novacal API. Wait a moment before retrying.\n```\n\nCalls to the Novacal API time out after 30 seconds.\n\n### Public routes\n\n| Route | Purpose |\n| --- | --- |\n| `GET /` | server name and status |\n| `GET /health` | health check |\n| `GET /.well-known/oauth-protected-resource` | RFC 9728 metadata, with `/mcp` suffix variant |\n| `GET POST /authorize` | sign-in page and form post |\n| `POST /token`, `POST /register` | handled by OAuthProvider |\n| `POST /mcp` | the MCP endpoint, requires a bearer token |\n\n---\n\n## Links\n\n- [Novacal](https://novacal.io)\n- [Model Context Protocol](https://modelcontextprotocol.io)\n- [MCP registry entry](https://registry.modelcontextprotocol.io) — `io.github.ste7/novacal-mcp-server`\n", "bytes": 8464, "sha": "e4e7fcfe2d9b7452b9cfe1ba6aede5b1d5c131637437debb488d07dfbdf7eee9", "repo_slug": "ste7/novacal-mcp-server", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_ste7_novacal_mcp_server_084a8923/readme" }