blvd-mcp

MCP server for Boulevard salon/spa operations. Monitor shift utilization, manage calendar blocks, and control services through Claude or any MCP client.

Features

• Location Management - List all locations, get staff members
• Shift Utilization - Analyze how busy shifts are, find capacity bottlenecks
• Timeblock Management - Create/delete calendar blocks (lunch, training, BTB)
• Appointment Queries - Get appointments by location and date range
• Service Control - List, activate, and deactivate services business-wide

Quick Start

git clone https://github.com/austinntowns/blvd-mcp.git
cd blvd-mcp
npm install
cp .env.example .env
# Edit .env with your Boulevard credentials
npm run dev

Open http://localhost:3000/inspector to test.

Configuration

Environment Variables

BLVD_API_KEY=your_api_key        # Required
BLVD_API_SECRET=your_api_secret  # Required
BLVD_BUSINESS_ID=your_business_id # Required

Getting Boulevard Credentials

1. Go to Boulevard Developer Portal (dashboard.boulevard.io)
2. Create an Admin API key (not Client API)
3. Get your Business ID from account settings

Add to Claude Code

Add to ~/.mcp.json:

{
  "mcpServers": {
    "blvd": {
      "url": "http://localhost:3000/sse"
    }
  }
}

Or run as a command:

{
  "mcpServers": {
    "blvd": {
      "command": "npx",
      "args": ["tsx", "/path/to/blvd-mcp/index.ts"],
      "env": {
        "BLVD_API_KEY": "your-key",
        "BLVD_API_SECRET": "your-secret",
        "BLVD_BUSINESS_ID": "your-business-id"
      }
    }
  }
}

Available Tools

Tool	Description
list-locations	Get all Boulevard locations
get-staff	Get staff members for a location
get-shift-utilization	Analyze shift utilization over date range
get-busy-shifts	Find high-utilization shifts (capacity bottlenecks)
list-timeblocks	List blocked time for a location
create-timeblock	Create a calendar block
delete-timeblock	Remove a calendar block
get-appointments	Get appointments by location/date
list-services	List all services
get-service	Get service details
activate-service	Activate service at all locations
deactivate-service	Deactivate service at all locations

Utilization Calculation

utilization = booked_minutes / available_minutes

Available minutes = shift duration minus lunch and DNB (Do Not Book) blocks.

License

MIT