calcom-mcp

calcom-mcp is a FastMCP server for interacting with the Cal.com API, enabling large language models (LLMs) to connect to Cal.com's important features through tools, such as managing event types and bookings. Project statement: not affiliated with or endorsed by Cal.com; it is an independent developer's work.

Purpose

The server enables LLMs to programmatically manage event types, create bookings, and access Cal.com's scheduling data.

Main capabilities (available tools)

The server currently provides the following tools for LLM interaction:

• get_api_status(): Checks whether the Cal.com API key is configured in the environment and returns a status string.
• list_event_types(): Retrieves a list of all event types for the authenticated account and returns a dictionary containing the event type list or an error message.
• get_bookings(...): Retrieves a list of bookings from Cal.com, supports optional filters (event_type_id, user_id, status, date_from, date_to, limit), and returns a dictionary containing the booking list or an error message.
• create_booking(...): Creates a new booking for a specific event type and attendee, requires parameters such as start_time, attendee details, and event type identifier, and returns a dictionary containing booking details or an error message.
• list_schedules(...): Lists all schedules available to the authenticated user or a specific user/team, with optional filters: user_id, team_id, limit, and returns a dictionary containing the schedule list or an error message.
• list_teams(...): Lists all teams available to the authenticated user, with the optional filter: limit, and returns a dictionary containing the team list or an error message.
• list_users(...): Lists all users available to the authenticated account, with the optional filter: limit, and returns a dictionary containing the user list or an error message.
• list_webhooks(...): Lists all webhooks configured for the authenticated account, with the optional filter: limit, and returns a dictionary containing the webhook list or an error message. Note: All tools require the CALCOM_API_KEY environment variable to be set. If it is not set, the tools will return a structured error message.

Usage(Installation and running)

1. Preparation: A Cal.com account and API Key (v2) are required.
2. Clone or download the files: git clone https://github.com/Danielpeter-99/calcom-mcp.git cd calcom-mcp
3. Create a virtual environment (recommended): python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate
4. Install dependencies: pip install -r requirements.txt
5. Set the Cal.com API Key: The CALCOM_API_KEY environment variable must be set. The API key can be obtained from the Cal.com settings page (usually under Developer or Security settings). Linux/macOS: export CALCOM_API_KEY="your_actual_api_key_here" To make it permanent, add this line to your shell configuration file (such as .bashrc, .zshrc). Windows (PowerShell): $env:CALCOM_API_KEY="your_actual_api_key_here" To make it permanent, set it through System Properties > Environment Variables.
6. Run the server: After setup is complete, run the FastMCP server. The server will start at localhost:8010, and a warning will be displayed if CALCOM_API_KEY is not set.

Tool usage and error handling

All tools return an API response (dictionary or string) or a structured error message containing failure details. Error messages include the error type, HTTP status code (if applicable), and the response text from the Cal.com API. It is recommended to always check whether an error key exists in the response before using the returned data. The tools are designed to be robust, providing informative feedback for both successful and failed API calls.

Development notes

• The Cal.com API base URL is set to https://api.cal.com/v2。
• Authentication primarily uses a Bearer token and CALCOM_API_KEY.
• The create_booking tool uses the cal-api-version: 2024-08-13 header (as specified for this endpoint in the Cal.com API v2 documentation).
• API calls include error handling to provide informative responses.

Security Considerations

Never hardcode CALCOM_API_KEY directly into the source code. Always use environment variables as described in the setup instructions to keep the API key secure.