Shotgun MCP

<p align="center"> <a href="https://shotgun.live"> <img src="https://www.google.com/s2/favicons?domain=shotgun.live&sz=128" alt="Shotgun" width="72" height="72"> </a> </p>

<h1 align="center">🎟️ Shotgun MCP</h1>

<p align="center"> Serveur <b>MCP</b> (Model Context Protocol) <b>non officiel</b> qui expose les ventes de tes événements <a href="https://shotgun.live">Shotgun</a> à un assistant IA : billets, revenu net, remboursement potentiel, quotas par tarif et audience — le tout en <b>données agrégées</b>. </p>

<p align="center"> <a href="https://modelcontextprotocol.io">🔌 Model Context Protocol</a> · <a href="https://shotgun.live">🌐 Shotgun</a> </p>

---

✨ Ce que ça fait

Un serveur MCP en HTTP streamable que tu ajoutes comme connecteur dans un client compatible (Claude, etc.). L'assistant peut alors interroger tes ventes en langage naturel : « où en sont les ventes de ce soir ? », « quel est mon CA net ? », « combien de filles/gars ? ».

🛠️ Outils exposés

Outil	Description
list_events	Événements active (à venir / en cours), past (terminés) ou all
event_report	Rapport de ventes complet d'un événement (accepte un id, slug ou nom)
dashboard	Vue agrégée de tous les événements actifs (ventes, CA, CA net, restants)

📊 event_report renvoie

• Ventes : vendus, valides, scannés (détectés via ticket_scanned_at), annulés, restants, taux de remplissage
• Revenu : brut, frais Shotgun, net, remboursement potentiel ce soir (payés non scannés)
• Rythme : ventes sur la dernière heure / 24 h
• Tarifs : vendus / quota par type de billet, avec statut sold-out
• Audience (agrégée) : répartition filles/gars, top villes

⚠️ Aucune donnée personnelle n'est renvoyée — tout est agrégé (compteurs, pourcentages).

🚀 Installation

python3 -m venv venv
./venv/bin/pip install -r requirements.txt
cp .env.example .env   # puis renseigne tes identifiants

Configuration (.env)

SHOTGUN_TOKEN=ton_token_shotgun
SHOTGUN_ORGANIZER_ID=ton_id_organisateur
# Jeton d'authentification exigé des clients (Authorization: Bearer <token>)
MCP_AUTH_TOKEN=un_secret_long_et_aleatoire
MCP_HOST=127.0.0.1
MCP_PORT=8790
# Hôte public derrière le reverse proxy (anti-DNS-rebinding)
MCP_PUBLIC_HOST=shotgun-mcp.exemple.tld

Où trouver le SHOTGUN_TOKEN / SHOTGUN_ORGANIZER_ID : dans ton dashboard organisateur → intégration > API.

▶️ Lancer

./venv/bin/python server.py
# → http://127.0.0.1:8790/mcp

En production (PM2) :

pm2 start ecosystem.config.js
pm2 save

🌐 Exposition HTTPS (reverse proxy)

Le serveur écoute en local ; place un reverse proxy HTTPS devant (nginx/Caddy). Points importants pour le transport SSE du MCP :

location / {
    proxy_pass http://127.0.0.1:8790;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_buffering off;          # SSE : pas de buffering
    proxy_read_timeout 3600s;     # connexions longues
    chunked_transfer_encoding on;
}

Renseigne l'hôte public dans MCP_PUBLIC_HOST (sinon la protection anti-DNS-rebinding du MCP rejette les requêtes proxifiées).

🔌 Ajouter le connecteur

Endpoint : https://<ton-hôte>/mcp En-tête d'authentification : Authorization: Bearer <MCP_AUTH_TOKEN>

🔒 Sécurité

• Auth par jeton : si MCP_AUTH_TOKEN est défini, toute requête sans le bon Authorization: Bearer reçoit 401. Laisse-le vide uniquement en local.
• Anti-DNS-rebinding : seuls les hôtes listés (MCP_PUBLIC_HOST + localhost) sont acceptés.
• Les secrets vivent dans .env (non versionné). Aucune donnée personnelle des acheteurs n'est exposée.

🧱 Structure

shotgun-mcp/
├── server.py           # Serveur MCP (outils + auth + app HTTP)
├── shotgun_client.py   # Client async de l'API Shotgun (agrégation des stats)
├── requirements.txt
├── .env.example
├── ecosystem.config.js # PM2
└── README.md

---

⚠️ Avertissement / Mentions légales

Projet personnel et non officiel, en aucun cas affilié, associé, autorisé ni soutenu par Shotgun (Shotgun Live SAS). « Shotgun », le logo et les marques associées sont la propriété exclusive de leurs détenteurs respectifs, utilisés ici à des fins d'identification uniquement. Tu es responsable du respect des conditions d'utilisation de Shotgun. Utilisation à tes risques, sans garantie.

📄 Licence

MIT.