# Calendly MCP Server

An MCP (Model Context Protocol) server for integrating Calendly with AI agents. This server provides tools to list scheduled events, check time slot availability for specific event types, and generate single-use scheduling links natively from any agent using the MCP standard.

## Prerequisites

- [Bun](https://bun.sh/) (JavaScript runtime)
- A Calendly account with a Personal Access Token (can be generated in your Calendly Integrations > API & Webhooks settings).

## Setup Instructions

1. Clone the repository and navigate into the project directory:
   ```bash
   git clone <repository-url>
   cd calendly-mcp-server
   ```
2. Install dependencies using Bun:
   ```bash
   bun install
   ```
3. Set your Calendly API token as an environment variable. Create a `.env` file in the root of the project:
   ```bash
   CALENDLY_API_TOKEN="your_personal_access_token_here"
   ```

## Tools

### 1. `list_events`
Lists scheduled events from Calendly. It can filter by user, organization, status, and control the result count.
- **Example Input:** `{ "count": 5, "status": "active" }`
- **Example Output:** A JSON string containing the active events for the current user.

### 2. `get_availability`
Retrieves available time slots for a specific event type within a given date range. Validates that the requested range does not exceed Calendly's 31-day limit and only queries future dates.
- **Example Input:** 
  ```json
  { 
    "event_type": "https://api.calendly.com/event_types/12345", 
    "start_time": "2026-10-01T00:00:00Z", 
    "end_time": "2026-10-07T00:00:00Z" 
  }
  ```
- **Example Output:** A JSON string containing available slots.

### 3. `create_scheduling_link`
Creates a single-use scheduling link for a specific event type, preventing unauthorized re-use. Uses safe retry logic to prevent accidental duplicate link creation during network timeouts.
- **Example Input:** 
  ```json
  { 
    "owner": "https://api.calendly.com/event_types/12345", 
    "max_event_count": 1 
  }
  ```
- **Example Output:** A JSON string containing the new `booking_url`.

## Running the Server

Start the MCP server via `stdio` transport:
```bash
bun index.ts
```

## Running Tests

Run the test suite using Bun's native test runner:
```bash
bun test
```