calcom cli
代理本地CLI和MCP服务器 加州理工学院API v2.61个工具，涵盖14个资源组——预订、活动类型、日程、可用性时段、日历、webhooks、团队等。为人类操作员和人工智能代理而构建。
为什么选择calcom cli？
- 双模：相同的命令定义为CLI和MCP服务器供电——人机界面和代理界面之间没有漂移
- 61个MCP工具：Cal.com API v2全面覆盖预订、活动类型、时间表、时段、日历、网络挂钩、个人资料、外出、团队、会议、目的地日历、选定日历和条纹
- 本地代理：每个工具都有Zod验证的输入模式、结构化的JSON输出和LLM可以处理的描述性错误消息
- 零配置：适用于单个
CAL_API_KEY环境变量——无OAuth流，无需配置文件 - 坚韧的：自动重试，速率限制（429）和服务器错误（5xx）呈指数回退，30秒读取/15秒写入超时
安装
# From npm (global)
npm install -g calcom-cli
# Or use npx (no install)
npx calcom-cli profile me --pretty
# From source
git clone https://github.com/bcharleson/calcom-cli.git
cd calcom-cli
npm install && npm run build
npm link快速开始
# 1. Authenticate (interactive — saves to ~/.calcom-cli/config.json)
calcom login
# 2. Check your profile
calcom profile me --pretty
# 3. List upcoming bookings
calcom bookings list --status upcoming --pretty
# 4. Find available slots
calcom slots available \
--event-type-id 123 \
--start-time "2025-03-20T00:00:00Z" \
--end-time "2025-03-27T00:00:00Z" --pretty认证
三种身份验证方式，按优先级顺序检查：
| 优先级 | 方法 | 示例 |
|---|---|---|
| 1 | --api-key 旗帜 | calcom --api-key cal_live_xxxx profile me |
| 2 | CAL_API_KEY 有人是。 export CAL_API_KEY=cal_live_xxxx | |
| 3 | 配置文件 | calcom login （保存到 ~/.calcom-cli/config.json) |
从获取API密钥 Cal.com设置>开发人员>API密钥.
MCP服务器设置
MCP服务器将所有61个工具暴露给任何兼容MCP的AI客户端。
克劳德代码
claude mcp add calcom -- npx calcom-cli mcp
# Or with local install:
claude mcp add calcom -- node /path/to/calcom-cli/dist/mcp.js克劳德桌面
添加 ~/.claude/claude_desktop_config.json:
{
"mcpServers": {
"calcom": {
"command": "npx",
"args": ["-y", "calcom-cli", "mcp"],
"env": {
"CAL_API_KEY": "cal_live_xxxx"
}
}
}
}光标
添加到光标MCP设置(.cursor/mcp.json):
{
"mcpServers": {
"calcom": {
"command": "npx",
"args": ["-y", "calcom-cli", "mcp"],
"env": {
"CAL_API_KEY": "cal_live_xxxx"
}
}
}
}帆板运动
添加 ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"calcom": {
"command": "npx",
"args": ["-y", "calcom-cli", "mcp"],
"env": {
"CAL_API_KEY": "cal_live_xxxx"
}
}
}
}命令参考
身份验证命令
calcom login # Authenticate with Cal.com API key (interactive)
calcom logout # Remove stored credentials
calcom auth-status # Show current auth status + config pathMCP服务器
calcom mcp # Start the MCP server (stdio transport)______________________________________________________________________
预订（13个命令）
calcom bookings list [options] # List bookings
--status # upcoming, recurring, past, cancelled, unconfirmed
--attendee-email # Filter by attendee
--event-type-id # Filter by event type
--after-start # After this start time
--before-end # Before this end time
--sort-start # Sort by start time
--take # Number of results
--skip # Offset
calcom bookings get # Get booking details
calcom bookings create [options] # Create a booking
--event-type-id # (required) Event type ID
--start # (required) Start time
--attendee-name # (required) Attendee name
--attendee-email # (required) Attendee email
--attendee-timezone # (required) Attendee timezone
--guests # Comma-separated guest emails
--notes # Booking notes
calcom bookings cancel [--reason ]
calcom bookings confirm
calcom bookings decline [--reason ]
calcom bookings reschedule --start [--reason ]
calcom bookings mark-absence [--host] [--attendees ]
calcom bookings reassign
calcom bookings update-location --type [--link ] [--integration ]
calcom bookings attendees
calcom bookings add-attendee --name --email --timezone
calcom bookings add-guests --guests 事件类型（5个命令）
calcom event-types list # List event types
calcom event-types get # Get event type details
calcom event-types create [options] # Create event type
--title # (required) Event title
--slug # (required) URL slug
--length # (required) Duration in minutes
--description # Description
--schedule-id # Schedule to use
--slot-interval # Slot interval
--min-notice # Minimum booking notice
--before-buffer # Buffer before event
--after-buffer # Buffer after event
calcom event-types update [options]
calcom event-types delete 时间表（6个命令）
calcom schedules list # List all schedules
calcom schedules get # Get schedule details
calcom schedules default # Get default schedule
calcom schedules create [options] # Create schedule
--name # (required) Schedule name
--timezone # (required) Timezone
--default # Set as default
--availability # Availability rules JSON
calcom schedules update [options]
calcom schedules delete 插槽（5个命令）
calcom slots available [options] # Get available time slots
--event-type-id # (required) Event type ID
--start-time # (required) Range start
--end-time # (required) Range end
--timezone # Timezone for results
--duration # Duration override
calcom slots reserve --event-type-id --slot-utc
calcom slots get-reserved
calcom slots update-reserved --slot-utc
calcom slots delete-reserved 日历（5个命令）
calcom calendars list # List connected calendars
calcom calendars busy --date-from --date-to
calcom calendars check # Check connection status
calcom calendars save-credentials --type --username --password
calcom calendars disconnect Webhooks（5个命令）
calcom webhooks list # List webhooks
calcom webhooks get
calcom webhooks create [options] # Create webhook
--subscriber-url # (required) Endpoint URL
--triggers # (required) e.g. BOOKING_CREATED,BOOKING_CANCELLED
--secret # Signing secret
calcom webhooks update [options]
calcom webhooks delete 配置文件（2个命令）
calcom profile me # Get your profile
calcom profile update [options] # Update profile
--name # Display name
--timezone # Timezone
--time-format # Time format
--week-start # Week start day
--default-schedule-id 外出（4个命令）
calcom out-of-office list
calcom out-of-office create --start --end [--notes ]
calcom out-of-office update [options]
calcom out-of-office delete 团队（5个命令）
calcom teams list
calcom teams get
calcom teams create --name [--slug ] [--timezone ]
calcom teams update [options]
calcom teams delete 会议（5个命令）
calcom conferencing list # List connected apps
calcom conferencing default # Get default app
calcom conferencing set-default --app-slug
calcom conferencing connect --app-slug
calcom conferencing disconnect --app-slug 目标日历（1个命令）
calcom destination-calendars update --integration --external-id 所选日历（2个命令）
calcom selected-calendars add --integration --external-id --credential-id
calcom selected-calendars delete --integration --external-id --credential-id 条纹（3个命令）
calcom stripe check # Check Stripe connection
calcom stripe connect # Get Stripe Connect URL
calcom stripe save-credentials --code # Save OAuth credentials全局选项
| 选项 | 描述 |
|---|---|
--api-key | Cal.com API密钥（覆盖env/config） |
--pretty | 漂亮的打印JSON输出 |
--quiet | 抑制输出（仅退出代码） |
--fields | 输出中包含的逗号分隔字段 |
-V, --version | 显示版本 |
-h, --help | 显示任何命令的帮助 |
输出格式
所有命令都将JSON返回到stdout。错误将转到stderr。
# Default — compact JSON
calcom bookings list
# Pretty-printed
calcom bookings list --pretty
# Field filtering
calcom bookings list --fields "uid,startTime,endTime,status" --pretty
# Quiet mode (exit code only, 0 = success, 1 = error)
calcom bookings cancel abc123 --quiet建筑
src/
├── index.ts # CLI entry (Commander.js)
├── mcp.ts # MCP entry (stdio transport)
├── core/
│ ├── types.ts # CommandDefinition — single source of truth
│ ├── client.ts # CalcomClient (fetch + retry + backoff)
│ ├── auth.ts # resolveApiKey (flag → env → config)
│ ├── config.ts # ~/.calcom-cli/config.json (mode 0600)
│ ├── handler.ts # executeCommand (path/query/body routing)
│ ├── output.ts # JSON formatting + --fields filtering
│ └── errors.ts # CalcomError hierarchy
├── commands/
│ ├── index.ts # allCommands registry + registerAllCommands
│ ├── auth/ # login, logout, status
│ ├── bookings/ # 13 commands
│ ├── event-types/ # 5 commands
│ ├── schedules/ # 6 commands
│ ├── slots/ # 5 commands
│ ├── calendars/ # 5 commands
│ ├── webhooks/ # 5 commands
│ ├── profile/ # 2 commands
│ ├── out-of-office/ # 4 commands
│ ├── teams/ # 5 commands
│ ├── conferencing/ # 5 commands
│ ├── destination-calendars/ # 1 command
│ ├── selected-calendars/ # 2 commands
│ └── stripe/ # 3 commands
└── mcp/
└── server.ts # MCP tool registration from allCommands每个命令都是一个 CommandDefinition 对象具有：
- 名字 --MCP工具名称（例如。
bookings_list) - 组/子命令 --CLI路由（例如。
calcom bookings list) - 输入模式 --Zod模式（由CLI验证+MCP工具模式共享）
- 端点 --HTTP方法+路径模板
- fieldMappings --将每个字段路由到路径、查询或正文
- 处理器 -通过CalcomClient执行API调用
配置文件
储存于 ~/.calcom-cli/config.json 具有权限 0600:
{
"apiKey": "cal_live_xxxx",
"user_id": 12345,
"user_name": "John Doe",
"user_email": "john@example.com",
"username": "johndoe",
"time_zone": "America/New_York"
}Cal.com API详细信息
| 财产 | 价值 |
|---|---|
| 基本URL | https://api.cal.com/v2 |
| 认证 | Authorization: Bearer cal_live_xxxx |
| 版本标题 | cal-api-version: 2024-08-13 |
| 速率限制 | 120个请求/分钟 |
| 分页 | 基于偏移(take + skip) |
| 关键前缀 | cal_ （测试）， cal_live_ （生产） |
发展
git clone https://github.com/bcharleson/calcom-cli.git
cd calcom-cli
npm install
# Dev mode (no build needed)
npm run dev -- profile me --pretty
npm run dev -- bookings list --status upcoming --pretty
npm run dev:mcp # test MCP server
# Production build
npm run build # → dist/index.js + dist/mcp.js
npm run typecheck # TypeScript strict mode
# Adding a new command:
# 1. Add CommandDefinition in src/commands//index.ts
# 2. Export from the group's commands array
# 3. Import in src/commands/index.ts → allCommands
# 4. npm run build && calcom --help相关项目
此工具遵循与其他代理本机CLI/MCP工具相同的体系结构：
- calendly cli -API日历
- 即时cli -即时.ai API
- 海里奇气候 -HeyReach API
许可证
麻省理工学院