Calcom CLI

calcom cli

](https://www.npmjs.com/package/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

认证

三种身份验证方式，按优先级顺序检查：

从获取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          # 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

全局选项

输出格式

所有命令都将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详细信息

发展

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

许可证

麻省理工学院