@brandcast_app/zoomshift-mcp-server/README.md

Model Context Protocol server for ZoomShift employee scheduling. Use ZoomShift with Claude Desktop.

# ZoomShift MCP Server

[![npm version](https://badge.fury.io/js/@brandcast_app%2Fzoomshift-mcp-server.svg)](https://www.npmjs.com/package/@brandcast_app/zoomshift-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Model Context Protocol server for ZoomShift employee scheduling. Enables Claude Desktop and other MCP clients to interact with ZoomShift schedules through natural language.

## Features

- 📅 **View Schedules** - Get employee shifts for any date range
- 👥 **Employee Management** - List employees and their positions
- 📍 **Location Tracking** - View all locations in your schedule
- 🔍 **Smart Search** - Search shifts by employee, role, or location
- 🤖 **AI-Powered** - Natural language interface via Claude Desktop
- 🔒 **Secure** - Environment-based credential management

## Installation

### Quick Start with npx (Recommended)

No installation required! Configure Claude Desktop to use the server via npx:

```json
{
  "mcpServers": {
    "zoomshift": {
      "command": "npx",
      "args": ["-y", "@brandcast_app/zoomshift-mcp-server"],
      "env": {
        "ZOOMSHIFT_EMAIL": "your@email.com",
        "ZOOMSHIFT_PASSWORD": "your-password",
        "ZOOMSHIFT_SCHEDULE_ID": "your-schedule-id"
      }
    }
  }
}
```

### Global Installation

```bash
npm install -g @brandcast_app/zoomshift-mcp-server
```

## Configuration

### Finding Your Schedule ID

Your ZoomShift schedule ID is found in the URL when you're logged into ZoomShift:

```
https://app.zoomshift.com/58369/dashboard
                          ^^^^^
                    This is your schedule ID
```

### Claude Desktop Setup

1. Open your Claude Desktop config file:
   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
   - **Linux**: `~/.config/Claude/claude_desktop_config.json`

2. Add the ZoomShift MCP server configuration:

```json
{
  "mcpServers": {
    "zoomshift": {
      "command": "npx",
      "args": ["-y", "@brandcast_app/zoomshift-mcp-server"],
      "env": {
        "ZOOMSHIFT_EMAIL": "your@email.com",
        "ZOOMSHIFT_PASSWORD": "your-password",
        "ZOOMSHIFT_SCHEDULE_ID": "58369"
      }
    }
  }
}
```

3. Restart Claude Desktop

## Usage

Once configured, you can interact with ZoomShift using natural language in Claude Desktop:

### Example Prompts

```
"Show me all shifts for next week"
"Who is working tomorrow?"
"Find all shifts for John Smith this month"
"List all employees in the schedule"
"What locations do we have?"
"Search for server shifts this week"
```

## Available Tools

The server provides 6 MCP tools that Claude can use:

### 1. `zoomshift_get_shifts`
Get all shifts for a date range.

**Parameters:**
- `start_date` (string): Start date in YYYY-MM-DD format
- `end_date` (string): End date in YYYY-MM-DD format

### 2. `zoomshift_get_employee_shifts`
Get shifts for a specific employee.

**Parameters:**
- `employee_id` (string): Employee ID
- `start_date` (string): Start date in YYYY-MM-DD format
- `end_date` (string): End date in YYYY-MM-DD format

### 3. `zoomshift_get_locations`
Get all locations in the schedule.

### 4. `zoomshift_get_employees`
Get all employees in the schedule.

### 5. `zoomshift_get_positions`
Get all job positions/roles in the schedule.

### 6. `zoomshift_search_shifts`
Search for shifts by employee name, role, or location.

**Parameters:**
- `query` (string): Search query
- `start_date` (string): Start date in YYYY-MM-DD format
- `end_date` (string): End date in YYYY-MM-DD format

## Development

### Building from Source

```bash
git clone https://github.com/BrandCast-Signage/zoomshift-mcp-server.git
cd zoomshift-mcp-server
npm install
npm run build
```

### Running Locally

```bash
ZOOMSHIFT_EMAIL="your@email.com" \
ZOOMSHIFT_PASSWORD="your-password" \
ZOOMSHIFT_SCHEDULE_ID="58369" \
node dist/index.js
```

## Architecture

This MCP server uses:
- **Transport**: stdio (standard input/output)
- **Protocol**: Model Context Protocol (MCP)
- **API Client**: [@brandcast_app/zoomshift-api-client](https://www.npmjs.com/package/@brandcast_app/zoomshift-api-client)
- **Runtime**: Node.js 18+

## Troubleshooting

### "Missing required environment variables"

Make sure all three environment variables are set in your Claude Desktop config:
- `ZOOMSHIFT_EMAIL`
- `ZOOMSHIFT_PASSWORD`
- `ZOOMSHIFT_SCHEDULE_ID`

### "Authentication failed"

Verify your ZoomShift credentials are correct. Try logging into ZoomShift manually to confirm.

### "Schedule ID not found"

Double-check your schedule ID from the ZoomShift URL. It should be a number (e.g., "58369").

### Server not appearing in Claude Desktop

1. Verify the config file syntax is valid JSON
2. Restart Claude Desktop completely
3. Check Claude Desktop logs for errors

## Security

- Credentials are passed via environment variables (never hardcoded)
- Uses session-based authentication with ZoomShift
- No credential caching or persistence
- Follows MCP security best practices

## Related Projects

- [@brandcast_app/zoomshift-api-client](https://www.npmjs.com/package/@brandcast_app/zoomshift-api-client) - TypeScript client for ZoomShift API
- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification

## BrandCast Integration

If you're a BrandCast customer, you can use the **integrated version** which doesn't require manual configuration:

```json
{
  "mcpServers": {
    "zoomshift": {
      "url": "https://dev.brandcast.app/mcp/zoomshift",
      "transport": "http",
      "oauth": {
        "enabled": true
      }
    }
  }
}
```

This version uses OAuth and credentials are managed through the BrandCast platform.

## Support

- **Issues**: [GitHub Issues](https://github.com/BrandCast-Signage/zoomshift-mcp-server/issues)
- **Documentation**: [MCP Protocol](https://modelcontextprotocol.io/)
- **API Client**: [zoomshift-api-client docs](https://github.com/jduncan-rva/zoomshift-api-client)

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Acknowledgments

Built with:
- [Model Context Protocol SDK](https://github.com/modelcontextprotocol/sdk)
- [@brandcast_app/zoomshift-api-client](https://www.npmjs.com/package/@brandcast_app/zoomshift-api-client)

---

**Note**: This is an unofficial integration. Not affiliated with or endorsed by ZoomShift.

Made with ❤️ by the BrandCast Team