fluidapex/calendly-mcp-server

Calendly MCP Server

A production-ready Model Context Protocol (MCP) server for Calendly API integration, designed for Fluid Hive business operations.

Features

• 🔐 Secure Authentication: Personal Access Token and OAuth 2.0 support
• 📅 Complete API Coverage: All Calendly API v2 endpoints implemented
• 🔄 Real-time Webhooks: Event notifications and processing
• 🛠️ Business Automation: Email templates and workflow integration
• 📊 Analytics: Scheduling performance analysis and reporting
• 🚦 Rate Limiting: Intelligent request throttling
• 🔍 Comprehensive Logging: Structured logging with request tracing
• 🧪 Fully Tested: >90% test coverage with unit and integration tests
• 📖 Production Ready: Error handling, retries, and monitoring

Quick Start

Prerequisites

• Python 3.13+
• Calendly account with API access
• Personal Access Token or OAuth credentials

Installation

1. Clone and setup:

   git clone <repository-url>
   cd calendly-mcp-server
   
   # Create and activate virtual environment
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   
   # Install dependencies
   pip install -e .[dev]
   

2. Configure environment:

   cp .env.example .env
   # Edit .env with your Calendly credentials
   

3. Run the server:

   # Simple method (auto-detects configuration)
   ./run_server.sh
   
   # Or manually
   python -m calendly_mcp.server
   

Authentication Setup

Personal Access Token (Recommended)

1. Go to Calendly API Settings
2. Generate a Personal Access Token
3. Add to your .env file:

   CALENDLY_PERSONAL_ACCESS_TOKEN=your_token_here
   

1Password CLI Integration

The server includes built-in 1Password CLI integration for secure token management:

1. Store your Calendly token in 1Password:

   op item create --category "API Credential" --title "Calendly-mcp-token" \
     --field "token,concealed=your_calendly_token_here"
   

2. Enable 1Password integration:

   # Set in .env file
   USE_1PASSWORD=true
   CALENDLY_1PASSWORD_ITEM=Calendly-mcp-token
   

3. Run with 1Password integration:

   # Using the provided script (recommended)
   ./scripts/run_with_1password.sh
   
   # Or manually with environment variable
   USE_1PASSWORD=true python -m calendly_mcp.server
   

4. Test the integration:

   ./scripts/test_with_1password.sh
   

The server will automatically:

• Check if 1Password CLI is available
• Attempt to retrieve the token from the specified item
• Try multiple field types (token, password, credential, api_key)
• Fall back to environment variables if 1Password is unavailable

OAuth 2.0 (For Client Applications)

CALENDLY_CLIENT_ID=your_client_id
CALENDLY_CLIENT_SECRET=your_client_secret
CALENDLY_REDIRECT_URI=your_redirect_uri

MCP Tools Reference

The server provides 25+ MCP tools organized by functionality:

Authentication & Health

• calendly_health_check - Test API connectivity
• calendly_get_current_user - Get authenticated user info

User & Organization Management

• calendly_get_user - Get user by UUID
• calendly_get_organization - Get organization details
• calendly_list_organization_members - List team members

Event Types

• calendly_list_event_types - List all event types
• calendly_get_event_type - Get event type details
• calendly_create_event_type - Create new event type ⭐
• calendly_update_event_type - Update existing event type ⭐

Scheduled Events

• calendly_list_scheduled_events - List scheduled meetings
• calendly_get_scheduled_event - Get meeting details
• calendly_get_event_invitees - Get meeting participants
• calendly_cancel_event - Cancel scheduled meeting

Availability

• calendly_get_availability - Check available time slots
• calendly_get_user_busy_times - Get busy periods
• calendly_create_single_use_link - Generate one-time booking links

Webhooks

• calendly_create_webhook - Set up event notifications
• calendly_list_webhooks - List webhook subscriptions
• calendly_delete_webhook - Remove webhook

Business Integration

• calendly_generate_email_template - Create professional booking emails
• calendly_analyze_scheduling_data - Generate performance insights

⭐ New Calendly API features

Usage Examples

Basic Health Check

# Using the MCP tool
result = await tools.handle_tool_call("calendly_health_check", {})
print(result[0].text)  # {"status": "healthy", "user": "John Doe"}

Create Event Type

event_data = {
    "name": "Client Consultation",
    "duration": 60,
    "description_plain": "60-minute consultation call",
    "color": "#0069ff"
}

result = await tools.handle_tool_call("calendly_create_event_type", event_data)

Generate Email Template

template_data = {
    "event_type": "Discovery Call",
    "client_name": "Jane Smith",
    "scheduling_url": "https://calendly.com/yourname/discovery",
    "custom_message": "Looking forward to discussing your project!"
}

email = await tools.handle_tool_call("calendly_generate_email_template", template_data)
print(email[0].text)  # Professional email template

Analyze Scheduling Performance

analysis_data = {
    "start_date": "2024-01-01T00:00:00Z",
    "end_date": "2024-01-31T23:59:59Z",
    "organization_uri": "https://api.calendly.com/organizations/ORG_ID"
}

insights = await tools.handle_tool_call("calendly_analyze_scheduling_data", analysis_data)

Gmail Integration Patterns

The server is designed to work seamlessly with Gmail MCP tools:

Automated Client Onboarding

# 1. Create personalized event type for client
client_event = await calendly_create_event_type({
    "name": f"{client_name} - Project Planning",
    "duration": 60,
    "description_plain": f"Dedicated planning session for {client_name}'s project"
})

# 2. Generate professional email
email_content = await calendly_generate_email_template({
    "event_type": "Project Planning Session",
    "client_name": client_name,
    "scheduling_url": client_event.scheduling_url,
    "custom_message": "Let's plan your project timeline and requirements."
})

# 3. Send via Gmail MCP
await gmail_send_email({
    "to": client_email,
    "subject": f"Schedule Your Project Planning - {company_name}",
    "body": email_content
})

Follow-up Automation

# Monitor completed meetings and trigger follow-ups
completed_events = await calendly_list_scheduled_events({
    "status": "active",
    "min_start_time": yesterday,
    "max_start_time": today
})

for event in completed_events:
    # Auto-generate follow-up scheduling
    follow_up_email = await calendly_generate_email_template({
        "event_type": "Follow-up Meeting",
        "client_name": event.invitee_name,
        "scheduling_url": follow_up_event_url
    })

Webhook Processing

Set up real-time event processing:

# Create webhook for booking notifications
webhook = await calendly_create_webhook({
    "url": "https://your-app.com/webhooks/calendly",
    "events": ["invitee.created", "invitee.canceled"],
    "organization": "https://api.calendly.com/organizations/ORG_ID"
})

# Process incoming webhooks
def handle_webhook(payload, signature, timestamp):
    # Verify signature
    is_valid = client.verify_webhook_signature(
        payload.encode(), signature, timestamp
    )
    
    if not is_valid:
        raise ValueError("Invalid webhook signature")
    
    # Process event
    event_type = payload["event"]
    if event_type == "invitee.created":
        # New booking - send confirmation
        pass
    elif event_type == "invitee.canceled":
        # Booking canceled - update records
        pass

Configuration

Environment Variables

Rate Limiting

The client includes intelligent rate limiting:

• Default: 100 requests per minute
• Automatic backoff on rate limit errors
• Request queuing and throttling
• Configurable limits per environment

Error Handling

Comprehensive error handling for all scenarios:

• Authentication errors (401): Token validation
• Permission errors (403): Scope and access rights
• Rate limiting (429): Automatic retry with backoff
• Not found (404): Resource existence validation
• Server errors (5xx): Retry logic and fallback

Development

Setup Development Environment

# Install development dependencies
pip install -e .[dev]

# Install pre-commit hooks
pre-commit install

# Run tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

# Run linting
ruff check src/
mypy src/

Testing

The project includes comprehensive tests:

• Unit tests: Individual component testing
• Integration tests: Full API workflow testing
• Mock fixtures: Realistic test data
• Coverage reporting: >90% coverage maintained

# Run all tests
pytest

# Run specific test categories
pytest tests/unit/
pytest tests/integration/

# Run with verbose output
pytest -v

# Run specific test
pytest tests/unit/test_client.py::TestCalendlyClient::test_health_check

Code Quality

• Ruff: Fast Python linter and formatter
• MyPy: Static type checking
• Pre-commit: Automated code quality checks
• Conventional commits: Standardized commit messages

Deployment

Production Checklist

• Set LOG_LEVEL=INFO or WARNING
• Configure SECRET_KEY for token encryption
• Set up log file rotation
• Configure webhook endpoint security
• Set appropriate rate limits
• Monitor API usage and quotas
• Set up health check monitoring
• Configure backup authentication method

Docker Deployment

FROM python:3.13-slim

WORKDIR /app
COPY . .

RUN pip install -e .

CMD ["python", "-m", "calendly_mcp.server"]

Monitoring

The server includes built-in monitoring:

• Structured logging with request tracing
• Health check endpoint
• Rate limit monitoring
• Error tracking and reporting
• Performance metrics

Troubleshooting

Common Issues

Authentication Failed (401)

• Verify your Personal Access Token
• Check token permissions and scopes
• Ensure token hasn't expired

Rate Limited (429)

• Reduce request frequency
• Check current rate limits
• Implement request queuing

Webhook Signature Invalid

• Verify webhook secret configuration
• Check timestamp tolerance
• Validate payload encoding

Connection Timeouts

• Check network connectivity
• Verify API endpoint availability
• Review timeout configurations

Debug Mode

Enable debug logging for troubleshooting:

export LOG_LEVEL=DEBUG
python -m calendly_mcp.server

Health Check

Test server health:

# Using curl (if server exposes HTTP endpoint)
curl http://localhost:8080/health

# Using MCP tool
{"tool": "calendly_health_check", "arguments": {}}

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes with tests
4. Run the full test suite (pytest)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Development Guidelines

• Follow SOLID principles
• Maintain >90% test coverage
• Use type hints throughout
• Follow conventional commit format
• Update documentation for new features

License

MIT License - see file for details.

Support

• 📧 Email: dev@fluidhive.com
• 🐛 Issues: GitHub Issues
• 📖 Documentation:
• 💬 Discussions: GitHub Discussions

Built with ❤️ by Fluid Hive for seamless scheduling automation