Content
# MCP Sling Server
Model Context Protocol (MCP) server for the Sling API - a comprehensive scheduling and workforce management platform.
> **Quick Start:** New to this? See [QUICK_START.md](./QUICK_START.md) for a 5-minute setup guide!
## Features
This MCP server provides tools to interact with all major Sling API endpoints:
### Calendar & Scheduling
- **get_calendar** - Retrieve calendar and shift data for users
- **create_shift** - Create new shifts for employees
- **get_timesheets** - View timesheet data and actual hours worked
- **update_timesheet** - Modify timesheet entries
### User Management
- **get_users** - List all users in your organization
- **create_user** - Add new users
- **update_user** - Modify user information
### Organization Management
- **get_organization** - View organization details
- **get_organization_by_id** - Get specific organization info
- **switch_organization** - Switch between organizations
- **get_groups** - List organizational groups
### Reporting & Analytics
- **get_reports** - Access various reports (labor, schedule, attendance)
- **create_sales_record** - Record sales data for analytics
- **get_tags** - Retrieve available tags for categorization
### Settings
- **update_settings** - Modify organization or user settings
### Advanced
- **sling_api_call** - Make custom API calls to any Sling endpoint
## Installation
1. Clone this repository:
```bash
git clone <repository-url>
cd mcp-sling
```
2. Install dependencies:
```bash
npm install
```
3. Build the project:
```bash
npm run build
```
4. Get your Sling authorization token:
**IMPORTANT:** Due to CAPTCHA requirements on the Sling login endpoint, you need to obtain your authorization token from your browser.
Follow the detailed guide: **[TOKEN_GUIDE.md](./TOKEN_GUIDE.md)**
5. Create a `.env` file with your token:
```bash
cp .env.example .env
```
Edit `.env` and add your token:
```env
SLING_TOKEN=your-token-from-browser
SLING_SERVER=api
```
## Configuration
### Environment Variables
**Recommended approach (avoids CAPTCHA):**
- **SLING_TOKEN** (required) - Your Sling authorization token from browser
- See [TOKEN_GUIDE.md](./TOKEN_GUIDE.md) for instructions
- **SLING_SERVER** (optional) - API server to use (default: "api", use "test-api" for staging)
**Alternative (requires CAPTCHA - not recommended):**
- **SLING_EMAIL** - Your Sling account email
- **SLING_PASSWORD** - Your Sling account password
- Note: Currently not working due to CAPTCHA requirement on `/account/login` endpoint
### Claude Desktop Configuration
Add this to your Claude Desktop configuration file:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
**Recommended: Using token**
```json
{
"mcpServers": {
"sling": {
"command": "node",
"args": ["/absolute/path/to/mcp-sling/dist/index.js"],
"env": {
"SLING_TOKEN": "your-token-from-browser"
}
}
}
}
```
**Alternative: Using .env file**
```json
{
"mcpServers": {
"sling": {
"command": "node",
"args": ["/absolute/path/to/mcp-sling/dist/index.js"]
}
}
}
```
(Requires `.env` file with `SLING_TOKEN` configured)
## Usage Examples
Once configured, you can use the Sling tools through Claude. Here are some example queries:
### Get All Users
```
Can you get the list of all users in my Sling organization?
```
### View Calendar
```
Show me the calendar for user ID 12345 in organization 67890 for dates 2024-01-15
```
### Create a Shift
```
Create a shift for user 12345 starting at 2024-01-20T09:00:00Z and ending at 2024-01-20T17:00:00Z for the "Cashier" position
```
### Get Reports
```
Get the labor report for the period from 2024-01-01 to 2024-01-31
```
### Custom API Call
```
Make a GET request to /custom/endpoint with params {"filter": "active"}
```
## Authentication
This server handles authentication automatically using your configured credentials. The authentication flow:
1. On first request, the server logs in to Sling using your email/password
2. The authentication token is cached and reused for subsequent requests
3. If a token expires (401 error), the server automatically refreshes it
4. Tokens are typically valid for 1 hour
Note: The Sling API uses email/password authentication as documented in their [official examples](https://github.com/getsling/getsling-api-docs).
### About CAPTCHA
**Important Update:** As of November 2024, Sling has added CAPTCHA protection to the `/account/login` API endpoint. This means direct email/password authentication no longer works without solving a CAPTCHA challenge.
**Solution:** Use a pre-obtained authorization token from your browser instead. See [TOKEN_GUIDE.md](./TOKEN_GUIDE.md) for detailed instructions.
**Why this approach works:**
- Tokens obtained from browser sessions don't require CAPTCHA
- Tokens typically remain valid for weeks or months
- You only need to get a new token when it expires or you change your password
- This is the recommended approach until Sling provides an alternative API authentication method
## API Documentation
For detailed information about the Sling API endpoints and data formats, refer to:
- [Official Sling API Docs](https://api.getsling.com/)
- [Sling API GitHub Repository](https://github.com/getsling/getsling-api-docs)
## Development
### Build
```bash
npm run build
```
### Watch Mode
```bash
npm run watch
```
### Run Development Server
```bash
npm run dev
```
### Test Authentication
To verify your credentials work before using with Claude:
```bash
node test-auth.js
```
This will attempt to authenticate and show detailed debug information.
## Permissions
Your API access level matches your Sling user permissions:
- **Admin tokens** - Full access to all organization data
- **Employee tokens** - Limited to that user's information only
## Troubleshooting
### "No authorization token received from Sling API"
The server now includes detailed debug logging. Check your MCP server logs (Claude Desktop Developer Console) for:
- Response status code
- Response headers
- Response body
This will help identify where the token should be.
**Quick fixes:**
1. Verify credentials in `.env` are correct (no extra quotes/spaces)
2. Test login with curl:
```bash
curl -i -X POST https://api.getsling.com/account/login \
-H "Content-Type: application/json" \
-d '{"email":"your@email.com","password":"password"}'
```
3. Look for `authorization:` header in the response
**For detailed troubleshooting steps, see [TROUBLESHOOTING.md](./TROUBLESHOOTING.md)**
### Authentication Issues
- Verify your email and password are correct in `.env`
- Check that you can log in to Sling web app with these credentials
- Ensure you're using the correct server (api vs test-api)
- Make sure you're not using OAuth provider credentials (Google/Facebook)
### API Errors
- Check the error message for specific details
- Verify your user has permission to access the requested resource
- Ensure date formats are in ISO 8601 format (e.g., "2024-01-20T09:00:00Z")
### Connection Issues
- Verify you have internet connectivity
- Check if api.getsling.com is accessible
- Try using SLING_SERVER=test-api for the staging environment
### Debugging
The server logs detailed authentication information to stderr:
- All response headers from Sling API
- Response body content
- Token extraction attempts
View these logs in:
- **Claude Desktop**: Help → Developer Tools → Console
- **Terminal**: stderr output from the MCP server process
## License
MIT
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## Support
For issues with:
- **This MCP server**: Open an issue in this repository
- **Sling API**: Refer to [Sling API documentation](https://github.com/getsling/getsling-api-docs)
- **MCP Protocol**: See [MCP documentation](https://modelcontextprotocol.io/)
