---
tags: [note, MCP]
type: "note"
nature: documentation # Options : portrait, lieu, info, concept, script, process, tuto, none
ressource: true
univers: PERSO
projects:
  - "[[03_PROJETS/VPS-IA]]"
date: "[[01_JOURNAL/2026/2026-10-10]]"
priority: 10
description: "Installe les deux MCP Excalidraw : sentinel (canvas local) et maaker (génération file-based)."
---
# Installation MCP Excalidraw sur VPS (sentinel + maaker)

## Contexte

Objectif : connecter un MCP Excalidraw à OpenCode pour que l'agent puisse créer/éditer des diagrammes, et les visualiser sur le web.

## Constat sur l'instance existante

- Instance : `https://excalidraw.datagrandest.net/` (YunoHost) — **active** (répond, redirigée vers le SSO YunoHost).
* Cette instance a été installée via le catalogue des applications officielles de Yunohost
- L'éditeur est servi en **fichiers statiques par nginx** : **pas de port local dédié**, pas de processus Node.
- Pas de port local dédié. Les ports identifiés référencent des fichiers `.excalidraw` mais ne correspondent pas à l'instance installée (ex. : port `8090` = serveur **rclone** exposant un dossier de fichiers `.excalidraw` (stockage, pas l'éditeur)).
- Conséquence : se connecter à l'instance existante via MCP est complexe (SSO + fichiers statiques + accès admin requis pour injecter un bridge).

## Solution retenue (2 MCP en parallèle)

**1. `excalidraw-mcp-sentinel`** (canvas Excalidraw embarqué, 100 % local) + **application Redirect YunoHost** (reverse proxy) pour l'accès web.

- OpenCode accède au canvas en local (`127.0.0.1:3001`).
- Visualisation web via `https://excalidraw-mcp.datagrandest.net/` (Redirect → `http://127.0.0.1:3001`).
- L'instance existante `https://excalidraw.datagrandest.net/`, installé à partir du catalogue Yunohost, reste utilisée pour l'usage manuel.

**2. `maaker-excalidraw-mcp`** (génération de diagrammes depuis une description, layout auto) — ajouté en parallèle, **file-based**, aucun conflit (pas de port, espace de noms d'outils distinct `excalidraw-maaker`).

> Les 2 sont compatibles avec le workflow « vérité unique » : les fichiers `.excalidraw` stockés dans SilverBullet sont la référence. → Voir [[04_NOTES/VPS-IA_Utilisation-Excalidraw-MCP|Utilisation des MCP Excalidraw]].

## Installation côté OpenCode — sentinel

### 1. Installer le paquet (préfixe utilisateur)

```sh
mkdir -p ~/.npm-global
npm install -g --prefix ~/.npm-global excalidraw-mcp-sentinel
```

Binaire : `~/.npm-global/bin/excalidraw-mcp-sentinel` (v1.2.1).

### 2. Configurer le MCP dans OpenCode

Fichier : `~/.config/opencode/opencode.json` (global) — ajouter dans `mcp.servers` :

```json
"excalidraw": {
  "type": "local",
  "command": ["/var/lib/opencode/.npm-global/bin/excalidraw-mcp-sentinel"],
  "environment": {
    "CANVAS_PORT": "3001",
    "HOST": "127.0.0.1"
  }
}
```

> ⚠️ `HOST=127.0.0.1` est indispensable : par défaut le canvas écoute sur `localhost` (IPv6 `::1`), inaccessible en IPv4 pour nginx.

### 3. Vérifier

- `opencode mcp list` → `excalidraw` connecté (32 outils).
- `curl http://127.0.0.1:3001/health` → `{"status":"healthy",...}`.

## Configuration YunoHost (accès web)

1. Installer l'app **Redirect** (admin YunoHost → Applications).
2. Configurer :
   - Domaine : `excalidraw-mcp.datagrandest.net`
   - Type : **Reverse proxy** (pas « Redirect » simple)
   - Cible : `http://127.0.0.1:3001`
   - SSO : protégé (recommandé) ou public
3. Valider → `https://excalidraw-mcp.datagrandest.net/` affiche le canvas.

## Persistance

- Le canvas est hébergé par le **processus MCP excalidraw du service OpenCode** → actif 24/7 tant que le service tourne.
- Script de secours : `~/.opencode/bin/start-excalidraw-canvas.sh` (démarre `dist/server.js` si le health échoue), enregistré en `@reboot` (crontab).

## Installation côté OpenCode — maaker (génération)

### 1. Installer (venv Python dédié)

```sh
python3 -m venv ~/.venvs/maaker
~/.venvs/maaker/bin/pip install maaker-excalidraw-mcp
```

Binaire : `~/.venvs/maaker/bin/excalidraw-mcp` (v0.5.3, Python ≥ 3.10).

### 2. Configurer le MCP dans OpenCode

```json
"excalidraw-maaker": {
  "type": "local",
  "command": ["/var/lib/opencode/.venvs/maaker/bin/excalidraw-mcp"]
}
```

### 3. Vérifier

- `opencode mcp list` → `excalidraw-maaker` connecté (28 outils).
- Test : `create_flowchart` → génère un fichier `.excalidraw` valide (v2), analysable par `read_diagram`.

### Particularités

- **File-based** : écrit sur des chemins locaux (`output_path`/`file_path`) — pas de serveur, pas de port.
- **Layout auto** (Sugiyama) : entrée structurée haut niveau, centrage texte, liaisons flèches automatiques.
- **Parallélisme naturel** : 1 schéma = 1 fichier, aucun état partagé (contrairement au canvas sentinel).
- **Pont vers SB** : le fichier généré doit être poussé dans l'espace SilverBullet via l'API `/.fs` (l'IA le fait avec `curl` + token).

## Fonctionnement / usage (sentinel)

- **Canvas live** : les outils de dessin (`create_element`, `batch_create_elements`, `create_from_mermaid`) exigent que la page canvas soit **ouverte dans un navigateur** (WebSocket) → les éléments apparaissent en temps réel.
- **Sans navigateur** : `import_scene`, `delete_element`, `query_elements`, `describe_scene` fonctionnent (import/export/scène).
- Exemple : « dessine un schéma d'architecture avec un serveur, une API et une base » → éléments créés, visibles sur le canvas.

## Workspaces (tenants / projets)

- **Tenants** : isolation multi-espaces — `list_tenants`, `switch_tenant`.
- **Projets** : espaces de travail séparés — `list_projects`, `switch_project` (avec `createName` pour créer un nouveau projet).
- Projet actif par défaut : « Default ».

## Notes / dépannage

- Le titre de la page canvas (« Excalidraw POC - Backend API Integration ») est le **titre par défaut** du frontend embarqué — normal.
- `clear_canvas` nécessite une confirmation en 2 étapes (token) et peut échouer (400) sans frontend → utiliser `delete_element` individuellement.
- `batch_create_elements` exige `x`/`y` sur les flèches (champs obligatoires).
- Port 3000 déjà utilisé par SilverBullet → canvas sur **3001**.

## Voir aussi

- [[04_NOTES/VPS-IA_Utilisation-Excalidraw-MCP|Utilisation des MCP Excalidraw]] — exemples de prompts et workflow.