# TryBooking MCP Server

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that wraps the [TryBooking Reporting API](https://developer.trybooking.com/), letting AI assistants like Claude query bookings, events, sales reports, attendance scans, and more.

## Prerequisites

- Node.js 18+
- A TryBooking account with API access
- API Key and Secret Key from TryBooking Portal (`Integration Tools > API Management`)

## Installation

### Claude Code Plugin (Recommended)

The easiest way to install — use the Claude Code plugin marketplace:

```bash
/plugin marketplace add marek-knappe/TryBookingMCP
/plugin install trybooking-mcp@trybooking-marketplace
/reload-plugins
```

Then configure your API credentials (see [Setting Environment Variables](#setting-environment-variables) below).

### Manual Installation

```bash
git clone https://github.com/marek-knappe/TryBookingMCP.git
cd TryBookingMCP
npm install
npm run build
```

## Configuration

The server requires three environment variables:

| Variable | Required | Description |
|----------|----------|-------------|
| `TRYBOOKING_API_KEY` | Yes | Your TryBooking API key |
| `TRYBOOKING_SECRET_KEY` | Yes | Your TryBooking secret key |
| `TRYBOOKING_REGION` | Yes | Region code: `au` (Australia), `nz` (New Zealand), `uk` (United Kingdom), or `us` (United States) |

Get your API credentials from the TryBooking Portal under `Integration Tools > API Management`.

### Setting Environment Variables

Whether you installed via the plugin marketplace or manually, the MCP server needs your TryBooking credentials as environment variables.

**Option 1: Claude Code settings file (Recommended)**

Add the env vars to your Claude Code settings at `~/.claude/settings.json`:

```json
{
  "env": {
    "TRYBOOKING_API_KEY": "your-api-key",
    "TRYBOOKING_SECRET_KEY": "your-secret-key",
    "TRYBOOKING_REGION": "au"
  }
}
```

**Option 2: Shell environment**

Export them in your shell profile (`~/.bashrc`, `~/.zshrc`, `~/.config/fish/config.fish`, etc.):

```bash
export TRYBOOKING_API_KEY="your-api-key"
export TRYBOOKING_SECRET_KEY="your-secret-key"
export TRYBOOKING_REGION="au"
```

Then restart Claude Code for changes to take effect.

**Option 3: Project-level settings**

For project-specific configuration, add to `.claude/settings.json` in your project directory:

```json
{
  "env": {
    "TRYBOOKING_API_KEY": "your-api-key",
    "TRYBOOKING_SECRET_KEY": "your-secret-key",
    "TRYBOOKING_REGION": "au"
  }
}
```

> **Note:** Don't commit `.claude/settings.json` if it contains secrets — add it to `.gitignore`.

After configuring, run `/reload-plugins` in Claude Code to pick up the changes.

### Claude Code (Manual Setup)

If you installed manually (not via the plugin marketplace), add to your Claude Code settings (`~/.claude/settings.json` or project `.claude/settings.json`):

```json
{
  "mcpServers": {
    "trybooking": {
      "command": "node",
      "args": ["/absolute/path/to/TryBookingMCP/dist/index.js"],
      "env": {
        "TRYBOOKING_API_KEY": "your-api-key",
        "TRYBOOKING_SECRET_KEY": "your-secret-key",
        "TRYBOOKING_REGION": "au"
      }
    }
  }
}
```

### Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "trybooking": {
      "command": "node",
      "args": ["/absolute/path/to/TryBookingMCP/dist/index.js"],
      "env": {
        "TRYBOOKING_API_KEY": "your-api-key",
        "TRYBOOKING_SECRET_KEY": "your-secret-key",
        "TRYBOOKING_REGION": "au"
      }
    }
  }
}
```

## Available Tools

### Account

| Tool | Description |
|------|-------------|
| `get_account_transactions` | Retrieve account transactions for a date range |

### Bookings

| Tool | Description |
|------|-------------|
| `get_booking` | Fetch a specific booking by transaction ID |
| `get_bookings_by_date` | Get bookings within a date range |

### Events

| Tool | Description |
|------|-------------|
| `list_events` | List all events for the account |
| `get_event` | Get details for a specific event |
| `get_event_session` | Get event session details by session ID |
| `get_event_sections` | List sections for an event |
| `get_seat_status` | Get seat availability for a session and section |

### Fundraising

| Tool | Description |
|------|-------------|
| `get_fundraising` | Retrieve fundraising pages |

### Sales Reports

| Tool | Description |
|------|-------------|
| `get_ticket_sales` | Ticket sales by period (day/week/month/year) |
| `get_booking_sales` | Booking sales report (max 180 days) |
| `get_event_sales` | Event sales report (max 180 days) |
| `get_fundraising_sales` | Fundraising sales report |

### Attendance Scans

| Tool | Description |
|------|-------------|
| `get_scan_attendance` | Scan attendance for a session (one scan per ticket) |
| `get_scan_all` | All scan events for a session |

## Example Usage

Once configured, you can ask Claude things like:

- "List all my TryBooking events"
- "Show me bookings from 2025-01-01 to 2025-01-31"
- "Get ticket sales for last month grouped by week"
- "What's the seat availability for session X, section Y?"
- "Show my account transactions for this quarter"

## API Reference

This server wraps the [TryBooking Reporting API](https://developer.trybooking.com/). All endpoints use HTTP Basic Authentication and return JSON responses. The server uses API v1 for most endpoints and v2 for scan endpoints (which use string-based rule IDs).

## License

MIT