novacal-mcp-server

一个用于 Novacal 的远程 MCP 服务。它为你的 AI 客户端提供 8 个工具，用于读取活动类型、查看空闲时段，以及预约、改期或取消会议。

它以单个 Cloudflare Worker 的形式运行，并使用 Streamable HTTP 通信。你只需通过 OAuth 连接一次，粘贴 Novacal API 密钥，之后客户端便可正常使用。

---

连接

托管服务地址为 https://mcp.novacal.io/mcp。

Claude Code

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

Cursor、Windsurf 或任何带有 MCP 配置文件的客户端

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

Claude Desktop 和 claude.ai

添加自定义连接器并粘贴相同的 URL。

首次连接时，客户端会打开登录页面。粘贴 Novacal API 密钥并点击 Connect。设置就这么简单。

---

工具

工具	功能	参数
novacal_get_event_types	列出账户中的活动类型	scope（personal 或 team，可选）
novacal_get_event_type	获取一个活动类型	id
novacal_create_event_type	创建活动类型	name、slug、type、duration、hidden_from_profile、color + 10 个可选字段
novacal_get_availability	查询指定日期范围内某活动类型的空闲时段	event_type_id、start、end、timezone（可选）
novacal_get_events	列出账户中的活动	无
novacal_create_event	预约活动	event_type_id、start、end、timezone、time_format、location 和 form_field_answers（可选）
novacal_cancel_event	取消未来的活动	id、cancellation_reason（可选）
novacal_reschedule_event	改期未来的活动	id、start、end、timezone、time_format、user_role 和 form_field_answers（可选）

读取工具标记为只读且幂等。novacal_cancel_event 标记为破坏性操作，因此会在破坏性调用前征求确认的客户端会要求确认。

活动类型范围

novacal_get_event_types 接受一个可选的 scope：

{ "scope": "personal" }

使用 personal 获取你自己的活动类型，使用 team 获取团队活动类型。不填写则会同时获取两者。除非你要求查询团队活动类型，否则服务会提示模型优先选择 personal。

可用时段的日期范围

start 和 end 是普通的 YYYY-MM-DD 日期。日期范围包含起始日期，但不包含结束日期：

[start 00:00, end 00:00)

若要查询单日，请将次日作为 end：

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

这会返回 2026 年 5 月 29 日的可用时段。将相同日期同时传给 start 和 end 会形成空范围，因此不会返回任何内容。

时区

timezone 接受 IANA 名称，例如 Europe/Amsterdam、America/New_York 或 Asia/Tokyo。如果省略，默认值为 UTC。

连接时，服务会读取你的 Novacal 个人资料时区，并将其写入服务说明。因此，模型会按你的时区解读相对日期并显示时间，除非你要求使用其他时区。

---

身份验证的工作方式

1. 客户端针对 Worker 启动 OAuth 流程。
2. Worker 提供 /authorize，并要求输入你的 Novacal API 密钥。
3. Worker 通过 GET /v1/users/me 验证密钥。
4. Worker 将密钥加密后存入 OAuth 会话属性，并完成流程。

只有使用你的访问令牌才能还原密钥。密钥绝不会以可读形式写入存储，也不会回显到页面中，并且不会写入以未加密形式存储的授权元数据。

在客户端中移除连接不会撤销密钥。若要切断访问权限，请在 Novacal 中轮换密钥。

---

本地开发

部署需要 Node 20+ 和 Cloudflare 账号。

npm install
npm run dev

端点	URL
MCP	http://127.0.0.1:8787/mcp
登录页面	http://127.0.0.1:8787/authorize
健康检查	http://127.0.0.1:8787/health

npm run dev 使用 Wrangler 的 dev 环境。它会在本地模拟 KV 和 D1，并连接到 http://localhost:8010 上的 Novacal API，因此绝不会触及生产资源。

若要手动试用这些工具：

npx @modelcontextprotocol/inspector

检查

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

CI 会在每次推送和拉取请求时，使用 Node 20 运行 check、lint 和 test。

---

部署

创建一次 Cloudflare 资源：

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

将返回的 ID 复制到 wrangler.toml 中的 OAUTH_KV 和 DB 下，然后应用架构：

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

部署 production 环境：

npm run deploy

注意： user_credentials 表已弃用。凭据现在存放在加密的 OAuth 会话中，没有任何代码会读取或写入此表。保留该表和 DB 绑定，仅为确保现有部署仍能通过验证。

配置

名称	类型	值
NOVACAL_API_BASE_URL	var	生产环境为 https://api.novacal.io，开发环境为 http://localhost:8010
OAUTH_KV	KV 命名空间	OAuth 客户端、授权和令牌存储
DB	D1 数据库	已弃用，未使用

---

组成方式

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

处理函数是普通的异步函数，不依赖 MCP 导入，因此可以轻松单独测试。每个工具都会用 try/catch 包装其处理函数，并返回 isError 结果，而不是抛出异常。失败会以简短提示的形式传递给模型，而不是原始 JSON 数据：

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

调用 Novacal API 的超时时间为 30 秒。

公共路由

路由	用途
GET /	服务名称和状态
GET /health	健康检查
GET /.well-known/oauth-protected-resource	RFC 9728 元数据，另有 /mcp 后缀变体
GET POST /authorize	登录页面和表单提交
POST /token、POST /register	由 OAuthProvider 处理
POST /mcp	MCP 端点，需要 bearer 令牌

---

链接

• Novacal
• Model Context Protocol
• MCP 注册表条目 — io.github.ste7/novacal-mcp-server