# SavvyCal MCP Server

An MCP (Model Context Protocol) server that connects Claude to your [SavvyCal](https://savvycal.com) account. Ask Claude about your upcoming meetings, check your availability, book meetings, and manage your scheduling links — all in natural language.

## What you can do

- **"What meetings do I have this week?"** — list upcoming bookings with attendee details and join links
- **"When am I free for a 30-minute call next week?"** — check available slots for any scheduling link
- **"Book a meeting with john@example.com on Tuesday at 2pm"** — create a booking directly
- **"Cancel my 3pm meeting today"** — cancel a scheduled event
- **"Turn off my intro-call link while I'm on holiday"** — pause/resume scheduling links
- **"Show me all my booking types"** — list all your scheduling links with status and duration

## Tools

| Tool | Description |
|------|-------------|
| `savvycal_list_events` | List upcoming (and past) meetings with date filters and pagination |
| `savvycal_get_event` | Get full details for a specific event including join link |
| `savvycal_cancel_event` | Cancel a scheduled meeting |
| `savvycal_create_event` | Book a meeting on a scheduling link |
| `savvycal_list_scheduling_links` | List all your scheduling links |
| `savvycal_get_available_slots` | Get available time slots for a scheduling link |
| `savvycal_toggle_link` | Enable or disable a scheduling link |
| `savvycal_get_current_user` | Get your account info and timezone |

## Setup

### 1. Get your SavvyCal API key

1. Log in to SavvyCal
2. Go to **Settings → Developer Settings**
3. Click **Create a token** and give it a name (e.g. "Claude MCP")
4. Copy the token — you'll need it in the next step

### 2. Configure Claude Code (stdio, local use)

Add to your `.mcp.json` in your project root:

```json
{
  "mcpServers": {
    "savvycal": {
      "command": "npx",
      "args": ["savvycal-mcp-server"],
      "env": {
        "SAVVYCAL_API_KEY": "pt_secret_your_token_here"
      }
    }
  }
}
```

Or run directly:

```bash
SAVVYCAL_API_KEY=pt_secret_your_token_here npx savvycal-mcp-server
```

### 3. Configure for HTTP (remote/hosted deployment)

```bash
SAVVYCAL_API_KEY=pt_secret_your_token_here TRANSPORT=http PORT=3000 node dist/index.js
```

The server exposes:
- `POST /mcp` — MCP endpoint
- `GET /health` — Health check

## Development

```bash
# Clone and install
git clone https://github.com/your-username/savvycal-mcp-server
cd savvycal-mcp-server
npm install

# Set your API key
export SAVVYCAL_API_KEY=pt_secret_your_token_here

# Build
npm run build

# Run (stdio)
npm start

# Run (HTTP)
TRANSPORT=http npm start
```

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `SAVVYCAL_API_KEY` | ✅ Yes | — | Your SavvyCal personal access token |
| `TRANSPORT` | No | `stdio` | Transport mode: `stdio` or `http` |
| `PORT` | No | `3000` | Port for HTTP transport |

## Example conversations

**Checking your schedule:**
> "What meetings do I have tomorrow?"
> "Show me all bookings this month"
> "Did anyone cancel a meeting recently?"

**Checking availability:**
> "When am I free for a 30-minute intro call next week?"
> "What slots do I have open on my consultation link for Friday?"

**Booking a meeting:**
> "Book a 30-minute intro call with Sarah (sarah@acme.com) for next Monday at 10am"

**Managing links:**
> "Pause all my scheduling links — I'm going on holiday"
> "Re-enable my intro-call link"
> "How many active scheduling links do I have?"

## License

MIT