calendly-mcp-server

Calendly MCP 服务

一个 MCP（Model Context Protocol）服务，可将 Claude Desktop 和 Claude Code 连接到你的 Calendly 账户，实现自然语言日程管理。

安装

pip install calendly-mcp

获取 Calendly 个人访问令牌

1. 登录 Calendly
2. 前往 Settings > Integrations & Apps
3. 滚动到 API & Connectors，然后点击 API
4. 点击 Get a token now（或 Generate New Token）
5. 为令牌命名（例如“Claude MCP”），然后点击 Create Token
6. 立即复制令牌——之后将无法再次查看

配置

Claude Desktop

将以下内容添加到你的 claude_desktop_config.json：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "calendly": {
      "command": "calendly-mcp",
      "env": {
        "CALENDLY_ACCESS_TOKEN": "your-token-here",
        "LICENSE_KEY": "optional-premium-key"
      }
    }
  }
}

Claude Code

启动 Claude Code 前，设置环境变量：

export CALENDLY_ACCESS_TOKEN="your-token-here"
export LICENSE_KEY="optional-premium-key"   # only if you have a premium license

然后添加 MCP 服务：

claude mcp add calendly -- calendly-mcp

或者将其添加到项目的 .mcp.json：

{
  "mcpServers": {
    "calendly": {
      "command": "calendly-mcp",
      "env": {
        "CALENDLY_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}

环境变量

变量	必填	描述
CALENDLY_ACCESS_TOKEN	是	Calendly 个人访问令牌或 OAuth2 令牌
LICENSE_KEY	否	Lemon Squeezy 高级版许可证密钥
LOG_LEVEL	否	日志级别：DEBUG、INFO、WARNING、ERROR（默认：INFO）
CALENDLY_BASE_URL	否	覆盖 Calendly API 基础 URL（用于测试）

工具

免费版（7 个工具）

工具	描述	必需参数
list_upcoming_events	列出即将举行的已安排活动，可选择筛选条件	无（可选：count、min_start_time、max_start_time、status）
get_event_details	获取指定活动的完整详情，包括受邀者和地点	event_uuid
search_events	按受邀者姓名或邮箱搜索活动（不区分大小写的部分匹配）	query（可选：min_start_time、max_start_time）
check_availability	根据你的可用时间安排检查可预约时段	date_range_start、date_range_end
get_busy_times	获取指定日期范围内忙碌或不可用的时段	start_time、end_time
list_event_types	列出所有已配置的活动类型，包括名称、时长和状态	无
get_event_type_details	获取指定活动类型的详细配置	event_type_uuid

高级版（额外提供 5 个工具）

工具	描述	必需参数
create_one_off_event	为会议创建一次性预约链接	event_type_uuid、invitee_email、invitee_name、start_time
cancel_event	取消已安排的活动（会通知受邀者）	event_uuid（可选：reason）
reschedule_event	将活动改期到新的时间	event_uuid、new_start_time
get_scheduling_stats	获取预约分析数据：会议总数、平均时长、热门时段	min_start_time、max_start_time
get_invitee_insights	分析与特定联系人的会议模式	invitee_email

免费版与高级版

功能	免费版	高级版
查看即将举行的活动	是	是
获取活动详情	是	是
按受邀者搜索活动	是	是
检查可用时段	是	是
查看忙碌时段	是	是
列出活动类型	是	是
获取活动类型详情	是	是
创建预约链接	--	是
取消活动	--	是
活动改期	--	是
预约分析	--	是
受邀者洞察	--	是
价格	免费	$12/月

前往 nyxtools.lemonsqueezy.com/checkout 升级

使用示例

连接后，可以自然地与 Claude 对话：

查看你的日程

• “我这周有哪些会议？”
• “显示我明天的日程”
• “列出我接下来的 5 场会议”
• “我这个月有哪些会议被取消了？”

活动详情

• “告诉我更多关于下午 3 点会议的信息”
• “设计评审邀请了谁？”
• “我下一个通话的 Zoom 链接是什么？”

搜索活动

• “我有和 [email protected] 的会议吗？”
• “查找所有和 Sarah 的会议”
• “我上次和 Acme 团队见面是什么时候？”

查看空闲时间

• “我周四下午有空吗？”
• “我下周的空闲时间安排是什么样的？”
• “我明天什么时候有安排？”

活动类型

• “我设置了哪些活动类型？”
• “显示我的 30 分钟会议类型的详情”

安排会议（高级版）

• “安排周二下午 2 点与 [email protected] 进行 30 分钟通话”
• “安排下周三与 Jane Smith 开会”

取消和重新安排（高级版）

• “取消我明天下午 3 点的会议”
• “取消和 John 的通话——我有时间冲突”
• “把我下午 2 点的会议改到周四下午 4 点”
• “把和 Sarah 的通话改到下周一上午”

分析（高级版）

• “我这个月开了多少场会议？”
• “我的平均会议时长是多少？”
• “我和 John 开会总共花了多少时间？”

开发

设置

git clone https://github.com/nyxtools/calendly-mcp-server.git
cd calendly-mcp-server
python -m venv venv
source venv/bin/activate   # or venv\Scripts\activate on Windows
pip install -e ".[dev]"

运行测试

pytest
pytest --cov=calendly_mcp    # with coverage

代码检查

ruff check src/ tests/
ruff format src/ tests/
mypy src/

故障排除

“需要设置 CALENDLY_ACCESS_TOKEN”

你尚未设置 CALENDLY_ACCESS_TOKEN 环境变量。请确保在 claude_desktop_config.json（env 下）中配置该变量，或在运行 Claude Code 之前于 shell 中导出该变量。

401 未授权错误

你的 Calendly 个人访问令牌无效或已被撤销。请在 Calendly 的 Settings > Integrations & Apps > API 中生成新令牌，并更新配置。

429 速率限制错误

Calendly API 会强制执行速率限制。MCP 服务会自动采用指数退避策略重试，但如果持续出现速率限制错误，请降低请求频率或等待几分钟。

连接错误

• 确认你的网络连接正常
• 检查你的网络是否可以访问 api.calendly.com
• 如果使用代理，请确保 httpx 可以访问 Calendly API

未显示高级版工具

• 确认环境中的 LICENSE_KEY 设置正确
• 检查服务日志中是否有许可证验证错误（LOG_LEVEL=DEBUG）
• 确保你的高级版订阅在 nyxtools.lemonsqueezy.com 处于有效状态

Claude Desktop 中的服务无法启动

• 确认 command 路径正确（calendly-mcp 必须位于 PATH 中）
• 尝试直接在终端中运行 calendly-mcp，检查是否有错误
• 在 Windows 上，你可能需要使用可执行文件的完整路径

许可证

MIT —— 详情请参阅 LICENSE。

版权所有 (c) 2026 NyxTools