Novacal Mcp Server

io.github.ste7Published by GitHub account ste7v0.1.0Updated Oct 25, 2026

Manage Novacal event types, availability, and bookings.

VerifiedStreamable HTTPWeb executableProductivity & WorkflowCommunication & Collaboration

Overview

AI-generated overview

Remote Novacal MCP server that lets an AI assistant list event types, check availability, and book, reschedule, or cancel meetings.

What you can do
List and fetch event types, with an optional personal or team scope, and create new event types with name, slug, duration, and color settings. Look up free availability slots for an event type over a date range in a chosen timezone. List events on the account. Book a new event with start, end, timezone, location, and form answers. Reschedule or cancel future events, optionally with a cancellation reason.
When to use it
Useful when you manage scheduling in Novacal and want an assistant to answer availability questions, propose slots, or create, move, and cancel meetings without opening the Novacal interface.
Requirements
A remote Streamable HTTP endpoint at mcp.novacal.io/mcp, added as an HTTP MCP server or custom connector. OAuth sign-in on first connect, where you paste a Novacal API key that is verified against the account. No local runtime needed for the hosted server.
Before you install
You supply a Novacal API key during OAuth; it is encrypted into the session, but removing the connection does not revoke it, so rotate the key in Novacal to cut off access. The server can create event types and book, reschedule, or cancel events, which changes real calendar data; cancellation is marked destructive and clients may prompt first.

Installation

In SourceWeft

  1. Open Novacal Mcp Server in the dashboard and add it to a workspace.
  2. Connect the required credentials. They are stored privately and never shown on public pages.
  3. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.ste7%2Fnovacal-mcp-server/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config. The client completes OAuth sign-in on first connect.

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

README

[Novacal MCP Server]

[CI status] [Transport: Streamable HTTP] [Tools: 8] [Deploys to Cloudflare Workers] [Last commit]

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

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

ToolWhat it doesArguments
novacal_get_event_typesList event types on the accountscope (personal or team, optional)
novacal_get_event_typeFetch one event typeid
novacal_create_event_typeCreate an event typename, slug, type, duration, hidden_from_profile, color + 10 optional fields
novacal_get_availabilityFree slots for an event type in a date rangeevent_type_id, start, end, timezone (optional)
novacal_get_eventsList events on the accountnone
novacal_create_eventBook an eventevent_type_id, start, end, timezone, time_format, location and form_field_answers (optional)
novacal_cancel_eventCancel a future eventid, cancellation_reason (optional)
novacal_reschedule_eventMove a future eventid, 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 installnpm run dev
EndpointURL
MCPhttp://127.0.0.1:8787/mcp
Sign-in pagehttp://127.0.0.1:8787/authorize
Health checkhttp://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 --noEmitnpm run lint     # biome checknpm run format   # biome check --writenpm 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_KVnpx wrangler d1 create novacal-mcp-server-db

Copy the returned IDs into 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

NameTypeValue
NOVACAL_API_BASE_URLvarhttps://api.novacal.io in production, http://localhost:8010 in dev
OAUTH_KVKV namespaceOAuth client, grant, and token storage
DBD1 databaselegacy, 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

RoutePurpose
GET /server name and status
GET /healthhealth check
GET /.well-known/oauth-protected-resourceRFC 9728 metadata, with /mcp suffix variant
GET POST /authorizesign-in page and form post
POST /token, POST /registerhandled by OAuthProvider
POST /mcpthe MCP endpoint, requires a bearer token

Links

Source: README.md at commit 0b0b457

Tools

0
This server asks you to sign in, so SourceWeft could not read its tools without an account and has not indexed them. What a connected account sees can depend on that account and its permissions.

Version history

1
  1. v0.1.0LatestSep 16, 2026

Score

75% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

    Declare a license in the repository or the registry entry.