Scrumbo API & MCP server — developer docs

Authentification

Chaque requête nécessite une clé API personnelle. Créez-en une sur votre page de compte — elle n'est affichée qu'une fois, copiez-la donc immédiatement.

Envoyez-la comme jeton bearer à chaque requête :

Authorization: Bearer sbo_your_key_here

API REST

L'API est disponible à https://scrumbo.com/api/v1 et renvoie du JSON. Une clé a exactement vos droits d'accès : elle n'atteint que les projets et boards dont vous êtes propriétaire, membre ou administrateur.

Méthode	Chemin	Description	Accès requis
GET	`/projects`	Lister les projets auxquels vous avez accès	Toute clé
GET	`/projects/:token/boards`	Lister les boards d'un projet	Viewer
GET	`/boards/:boardid`	Récupérer un board avec ses statuts et ses stories	Viewer
GET	`/boards/:boardid/statuses`	Lister les statuts d'un board	Viewer
GET	`/boards/:boardid/stories`	Lister les stories d'un board, éventuellement filtrées par statut ou assigné	Viewer
GET	`/boards/:boardid/stories/:storyid`	Récupérer une story	Viewer
POST	`/boards/:boardid/stories`	Créer une story	Editor
PATCH	`/boards/:boardid/stories/:storyid`	Mettre à jour les champs d'une story	Editor
POST	`/boards/:boardid/stories/:storyid/status`	Changer le statut d'une story	Editor ou contributor
DELETE	`/boards/:boardid/stories/:storyid`	Supprimer une story	Editor
POST	`/boards/:boardid/stories/:storyid/comments`	Ajouter un commentaire à une story	Commenter
Compte, facturation et factures
GET	`/account`	Récupérer votre compte : plan, limites d'utilisation du plan gratuit et coordonnées de facturation	Toute clé
GET	`/invoices`	Lister vos factures	Toute clé
GET	`/invoices/:invoiceid` · `…/pdf`	Récupérer le détail d'une facture, ou la télécharger en PDF	Toute clé
Banque d'heures
GET	`/projects/:token/hourbank` · `…/transactions`	Récupérer les paramètres et le solde actuel de la banque d'heures d'un projet, ou son journal de transactions	Viewer
POST	`…/hourbank/settings` · `…/entries`	Configurer la banque d'heures d'un projet, ou y ajouter un achat/ajustement	Propriétaire du projet
Équipe
GET	`/team`	Lister votre équipe interne sur tous vos projets et feature boards	Toute clé
Feature boards
GET	`/featureboards`	Lister les feature boards dont vous êtes membre	Membre du board
POST	`/featureboards`	Créer un feature board	Plan payant
GET	`/featureboards/:boardid`	Récupérer un feature board avec ses features, votes, commentaires et membres	Membre du board
POST	`…/features` · `…/vote` · `…/comments`	Soumettre une feature request, voter pour l'une d'elles, ou ajouter un commentaire	Membre du board
PATCH POST DELETE	`…/features/:featureid` · `…/status`	Mettre à jour, définir le statut, ou supprimer une feature request	Administrateur du board
DELETE	`…/comments/:commentid`	Supprimer un commentaire de feature request	Auteur du commentaire ou administrateur du board
POST DELETE	`/featureboards/:boardid/members` · `…/:userid/admin` · `…/:userid/external`	Ajouter, promouvoir/rétrograder, reclasser ou retirer un membre du board	Administrateur du board

« Editor ou contributor » couvre aussi les developers, qui peuvent changer le statut mais pas modifier le texte de la story.

Exemple :

curl https://scrumbo.com/api/v1/boards/123/stories \
  -H "Authorization: Bearer sbo_your_key_here"

curl -X POST https://scrumbo.com/api/v1/boards/123/stories \
  -H "Authorization: Bearer sbo_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"subject": "New story", "story": "Details go here"}'

Paramètres

Les corps de requête sont en JSON. Chaque paramètre ci-dessous est accepté aussi bien par l'API REST que par l'outil MCP correspondant.

Paramètres de chemin

Nom	Type	Obligatoire	Description
`:token`	string	Oui	Jeton du projet, tel que renvoyé par GET /projects.
`:boardid`	integer	Oui	Identifiant numérique du board, tel que renvoyé par GET /projects/:token/boards.
`:storyid`	integer	Oui	Identifiant numérique de la story, unique au sein de son board.

Paramètres de requête

GET /boards/:boardid/stories

Nom	Type	Obligatoire	Description
`status`	string	Non	Ne renvoie que les stories dans ce statut. La casse est ignorée lors du filtrage.
`assigned`	string	Non	Ne renvoie que les stories portant ce nom d'assigné. La casse est ignorée lors du filtrage.

Champs d'une story (création et mise à jour)

POST /boards/:boardid/stories · PATCH /boards/:boardid/stories/:storyid

Nom	Type	Obligatoire	Description
`subject`	string	À la création	Titre court, 500 caractères maximum. Obligatoire à la création ; les valeurs plus longues sont rejetées.
`story`	string	Non	Corps de la story. Le HTML est autorisé mais nettoyé côté serveur : les balises et attributs non pris en charge sont supprimés.
`status`	string	Non	Doit correspondre exactement à l'un des statuts du projet, casse comprise. À la création, un statut inconnu ou absent bascule sur le premier statut du board ; à la mise à jour, un statut inconnu est rejeté.
`assigned`	string	Non	Nom de l'assigné, texte libre. Ce n'est qu'une étiquette : cela ne relie pas la story à un compte Scrumbo.
`requester`	string	Non	Nom de la personne à l'origine de la demande, texte libre.
`scope`	string	Non	Étiquette de périmètre courte, 100 caractères maximum. Les valeurs plus longues sont rejetées.
`comment`	string	Non	Ancien champ de texte libre stocké sur la story elle-même. Il n'apparaît pas dans l'interface web — pour ajouter un commentaire visible, utilisez le point de terminaison des commentaires ci-dessous.
`notify`	boolean	Non	Envoie un e-mail aux abonnés du board et de la story à propos de cette modification. Faux par défaut.

Tout champ absent de cette liste est ignoré plutôt que rejeté.
Une mise à jour doit fournir au moins un de ces champs ; seuls les champs envoyés sont modifiés.
Relier une story à un compte Scrumbo (le sélecteur d'assigné) n'est pas possible via l'API.

Déplacer une story

POST /boards/:boardid/stories/:storyid/status

Nom	Type	Obligatoire	Description
`status`	string	Oui	Statut cible. Doit correspondre exactement à l'un des statuts du projet, casse comprise.
`notify`	boolean	Non	Envoie un e-mail aux abonnés du board et de la story à propos de cette modification. Faux par défaut.

Ajouter un commentaire

POST /boards/:boardid/stories/:storyid/comments

Nom	Type	Obligatoire	Description
`comment`	string	Oui	Texte du commentaire, en texte brut. Il est échappé avant stockage : le HTML s'affiche littéralement au lieu d'être interprété.
`name`	string	Non	Nom d'auteur affiché sur le commentaire. Par défaut, le nom du compte de la clé API.
`notify`	boolean	Non	Envoie un e-mail aux abonnés du board et de la story à propos de cette modification. Faux par défaut.

Les requêtes rejetées renvoient le statut HTTP correspondant (400, 403 ou 404) et un corps JSON :

{"error": "subject must be at most 500 characters"}

Serveur MCP

Scrumbo fournit un serveur MCP autonome qui expose l'API REST sous forme d'outils, afin qu'un assistant compatible MCP comme Claude Desktop ou Claude Code puisse utiliser directement vos boards. Node.js 20 ou plus récent est requis.

Télécharger le serveur MCP (ZIP)

Décompressez-le et installez ses dépendances une fois :
```
unzip scrumbo-mcp.zip
cd scrumbo-mcp
npm install
```
Créez une clé API sur votre page de compte et copiez-la.
Enregistrez le serveur auprès de votre client MCP, par exemple :

{
  "mcpServers": {
    "scrumbo": {
      "command": "node",
      "args": ["/absolute/path/to/scrumbo-mcp/index.js"],
      "env": {
        "SCRUMBO_API_KEY": "sbo_your_key_here",
        "SCRUMBO_API_URL": "https://scrumbo.com/api/v1"
      }
    }
  }
}

Outils :

Description	Accès requis
`list_projects`	Toute clé
`list_boards`, `get_board`, `list_stories`, `get_story`, `list_statuses`	Viewer
`add_comment`	Commenter
`create_story`, `update_story`, `move_story`, `delete_story`	Editor
`get_account`, `list_invoices`, `get_invoice`, `get_invoice_pdf`, `get_team`	Toute clé
`get_hourbank`, `list_hourbank_transactions`	Viewer
`save_hourbank_settings`, `add_hourbank_entry`	Propriétaire du projet
`list_feature_boards`, `get_feature_board`, `create_feature`, `vote_feature`, `add_feature_comment`	Membre du board
`create_feature_board`	Plan payant
`update_feature`, `set_feature_status`, `delete_feature`, `add_feature_board_member`, `set_feature_board_member_admin`, `set_feature_board_member_external`, `remove_feature_board_member`	Administrateur du board
`delete_feature_comment`	Auteur du commentaire ou administrateur du board

À retenir

Une clé a exactement vos droits d'accès — quiconque la détient peut agir en votre nom dans ce périmètre, traitez-la donc comme un mot de passe.
Révoquez une clé à tout moment depuis votre page de compte ; tout ce qui l'utilise cesse alors immédiatement de fonctionner.
Le serveur MCP lui-même n'a aucun accès à la base de données — c'est un client HTTP léger qui n'a jamais plus de droits que la clé que vous lui fournissez.

API et serveur MCP