使用说明

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 path

MCP服务器

calcom mcp                      # Start the MCP server (stdio transport)

预订（13个命令）

calcom bookings list [options]                   # List bookings
  --status <status>         # upcoming, recurring, past, cancelled, unconfirmed
  --attendee-email <email>  # Filter by attendee
  --event-type-id <id>      # Filter by event type
  --after-start <iso>       # After this start time
  --before-end <iso>        # Before this end time
  --sort-start <asc|desc>   # Sort by start time
  --take <n>                # Number of results
  --skip <n>                # Offset

calcom bookings get <bookingUid>                 # Get booking details
calcom bookings create [options]                 # Create a booking
  --event-type-id <id>       # (required) Event type ID
  --start <iso>              # (required) Start time
  --attendee-name <name>     # (required) Attendee name
  --attendee-email <email>   # (required) Attendee email
  --attendee-timezone <tz>   # (required) Attendee timezone
  --guests <emails>          # Comma-separated guest emails
  --notes <text>             # Booking notes

calcom bookings cancel <bookingUid> [--reason <text>]
calcom bookings confirm <bookingUid>
calcom bookings decline <bookingUid> [--reason <text>]
calcom bookings reschedule <bookingUid> --start <iso> [--reason <text>]
calcom bookings mark-absence <bookingUid> [--host] [--attendees <emails>]
calcom bookings reassign <bookingUid>
calcom bookings update-location <bookingUid> --type <type> [--link <url>] [--integration <name>]
calcom bookings attendees <bookingUid>
calcom bookings add-attendee <bookingUid> --name <name> --email <email> --timezone <tz>
calcom bookings add-guests <bookingUid> --guests <emails>

事件类型（5个命令）

calcom event-types list                          # List event types
calcom event-types get <eventTypeId>             # Get event type details
calcom event-types create [options]              # Create event type
  --title <title>            # (required) Event title
  --slug <slug>              # (required) URL slug
  --length <minutes>         # (required) Duration in minutes
  --description <text>       # Description
  --schedule-id <id>         # Schedule to use
  --slot-interval <min>      # Slot interval
  --min-notice <min>         # Minimum booking notice
  --before-buffer <min>      # Buffer before event
  --after-buffer <min>       # Buffer after event

calcom event-types update <eventTypeId> [options]
calcom event-types delete <eventTypeId>

时间表（6个命令）

calcom schedules list                            # List all schedules
calcom schedules get <scheduleId>                # Get schedule details
calcom schedules default                         # Get default schedule
calcom schedules create [options]                # Create schedule
  --name <name>              # (required) Schedule name
  --timezone <tz>            # (required) Timezone
  --default                  # Set as default
  --availability <json>      # Availability rules JSON

calcom schedules update <scheduleId> [options]
calcom schedules delete <scheduleId>

插槽（5个命令）

calcom slots available [options]                 # Get available time slots
  --event-type-id <id>      # (required) Event type ID
  --start-time <iso>        # (required) Range start
  --end-time <iso>          # (required) Range end
  --timezone <tz>           # Timezone for results
  --duration <min>          # Duration override

calcom slots reserve --event-type-id <id> --slot-utc <iso>
calcom slots get-reserved <uid>
calcom slots update-reserved <uid> --slot-utc <iso>
calcom slots delete-reserved <uid>

日历（5个命令）

calcom calendars list                            # List connected calendars
calcom calendars busy --date-from <date> --date-to <date>
calcom calendars check <credentialId>            # Check connection status
calcom calendars save-credentials --type <type> --username <user> --password <pass>
calcom calendars disconnect <credentialId>

Webhooks（5个命令）

calcom webhooks list                             # List webhooks
calcom webhooks get <webhookId>
calcom webhooks create [options]                 # Create webhook
  --subscriber-url <url>    # (required) Endpoint URL
  --triggers <events>       # (required) e.g. BOOKING_CREATED,BOOKING_CANCELLED
  --secret <secret>         # Signing secret

calcom webhooks update <webhookId> [options]
calcom webhooks delete <webhookId>

配置文件（2个命令）

calcom profile me                                # Get your profile
calcom profile update [options]                  # Update profile
  --name <name>             # Display name
  --timezone <tz>           # Timezone
  --time-format <12|24>     # Time format
  --week-start <day>        # Week start day
  --default-schedule-id <id>

外出（4个命令）

calcom out-of-office list
calcom out-of-office create --start <date> --end <date> [--notes <text>]
calcom out-of-office update <entryId> [options]
calcom out-of-office delete <entryId>

团队（5个命令）

calcom teams list
calcom teams get <teamId>
calcom teams create --name <name> [--slug <slug>] [--timezone <tz>]
calcom teams update <teamId> [options]
calcom teams delete <teamId>

会议（5个命令）

calcom conferencing list                         # List connected apps
calcom conferencing default                      # Get default app
calcom conferencing set-default --app-slug <slug>
calcom conferencing connect --app-slug <slug>
calcom conferencing disconnect --app-slug <slug>

目标日历（1个命令）

calcom destination-calendars update --integration <type> --external-id <id>

所选日历（2个命令）

calcom selected-calendars add --integration <type> --external-id <id> --credential-id <id>
calcom selected-calendars delete --integration <type> --external-id <id> --credential-id <id>

条纹（3个命令）

calcom stripe check                              # Check Stripe connection
calcom stripe connect                            # Get Stripe Connect URL
calcom stripe save-credentials --code <code>     # Save OAuth credentials

全局选项

选项	描述
`--api-key <key>`	Cal.com API密钥（覆盖env/config）
`--pretty`	漂亮的打印JSON输出
`--quiet`	抑制输出（仅退出代码）
`--fields <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/<group>/index.ts
# 2. Export from the group's commands array
# 3. Import in src/commands/index.ts → allCommands
# 4. npm run build && calcom <group> <subcommand> --help

许可证

麻省理工学院

Cal.com命令行工具

使用说明

calcom cli

为什么选择calcom cli？

安装

快速开始

认证

MCP服务器设置

克劳德代码

克劳德桌面

光标

帆板运动

命令参考

身份验证命令

MCP服务器

预订（13个命令）

事件类型（5个命令）

时间表（6个命令）

插槽（5个命令）

日历（5个命令）

Webhooks（5个命令）

配置文件（2个命令）

外出（4个命令）

团队（5个命令）

会议（5个命令）

目标日历（1个命令）

所选日历（2个命令）

条纹（3个命令）

全局选项

输出格式

建筑

配置文件

Cal.com API详细信息

发展

相关项目

许可证

使用说明

calcom cli

为什么选择calcom cli？

安装

快速开始

认证

MCP服务器设置

克劳德代码

克劳德桌面

光标

帆板运动

命令参考

身份验证命令

MCP服务器

预订（13个命令）

事件类型（5个命令）

时间表（6个命令）

插槽（5个命令）

日历（5个命令）

Webhooks（5个命令）

配置文件（2个命令）

外出（4个命令）

团队（5个命令）

会议（5个命令）

目标日历（1个命令）

所选日历（2个命令）

条纹（3个命令）

全局选项

输出格式

建筑

配置文件

Cal.com API详细信息

发展

相关项目

许可证

相关 MCP

iOS/macOS 构建 MCP 服务器与命令行工具

小红书内容访问服务

生物医学数据检索命令行与MCP服务

Windows命令行服务器

进程执行工具

Markdown微信排版发布工具