hedgedoc-mcp
Supports OIDC authentication through Keycloak as an external identity provider, scripting the Keycloak login flow to obtain a HedgeDoc service-account session.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
mcp-hedgedoc
Serveur MCP pour HedgeDoc 1.x — lit et crée des notes via un compte de
service unique, avec un vrai mode lecture seule pour la paire de
variantes ro/rw de LibreChat.
Ce que ce serveur peut et ne peut pas faire
HedgeDoc 1.x n'a aucune API à jetons : toute action passe par un
cookie de session obtenu via un vrai login. Ce serveur agit donc toujours
sous un compte de service partagé — jamais sous l'identité réelle de
la personne qui pose la question dans LibreChat. Toute note créée, toute
action listée dans /history, apparaît sous ce compte dans l'historique
HedgeDoc.
Il n'y a pas d'outil delete_note, et pour modifier le contenu d'une
note existante il faut passer par update_note. Explication :
HedgeDoc 1.x n'a aucun endpoint HTTP de mise à jour — POST /new/{alias} sur un alias déjà existant renvoie 409 Conflict
(vérifié sur le code source de HedgeDoc 1.11.1 et 1.12.0, identique dans
les deux). La modification du contenu ne se fait que via le canal
Socket.IO temps réel de l'éditeur web ; update_note pilote exactement
ce canal (voir « update_note et le canal temps réel » plus bas).
Related MCP server: hedgedoc-mcp-server
Outils exposés
Outil | Lecture seule | Description |
| oui | Contenu Markdown brut d'une note |
| oui | Titre, description, vues, dates |
| oui | Liste des révisions sauvegardées |
| oui | Contenu à une révision donnée |
| oui | Identité de la session actuelle (toujours le compte de service) |
| oui | Notes récemment consultées/épinglées par le compte de service |
| non | Crée une nouvelle note (jamais une modification) |
| non | Remplace tout le contenu d'une note existante (via le canal temps réel) |
Variables d'environnement
Variable | Obligatoire | Défaut | Description |
| oui | — | URL de base, ex. |
| non |
|
|
| non |
|
|
| non |
| Port d'écoute HTTP |
| non |
| Timeout des requêtes HTTP |
| non | — | CA interne, si nécessaire |
Selon HEDGEDOC_AUTH_MODE :
Mode | Variables requises |
|
|
|
|
|
|
Choisir le mode d'auth
Le bon mode dépend de la façon dont les comptes existent sur l'instance cible, pas du serveur MCP :
local— l'instance possède des comptes natifs HedgeDoc (config.email/CMD_EMAILactivés côté serveur, comptes créés par exemple viabin/manage_users). C'est le mode le plus simple : un seulPOST /login, rien de fragile. Il ne peut pas authentifier un compte créé par un fournisseur OAuth2/Keycloak — même avec les bonnes identités,POST /loginest rejeté.oidc— les utilisateurs de l'instance proviennent d'un IdP externe (ex. Keycloak,CMD_OAUTH2_*activés). Le serveur scripte la danse/auth/oauth2→ page de login Keycloak → callback. Voir la docstring deauth.pypour le détail et les limites (thème de login personnalisé, 2FA, actions requises sur le compte).cookie— contournement pour le debug : on fournit directement unconnect.siddéjà valide (ex. copié d'un navigateur). Le serveur vérifie quand même que le cookie est utilisable viaGET /me.
Comment savoir quel mode utiliser sur une instance inconnue ? Le
symptôme typique d'un mauvais mode est trompeur : en local sur une
instance Keycloak, le login « réussit » (HTTP 200, cookie posé) mais la
session est anonyme, et c'est GET /me qui renvoie
{"status": "forbidden"} — le serveur MCP le détecte et lève
AuthenticationError, mais si on ne passe pas par le MCP, on peut
longtemps chercher un problème de credentials. Pour trancher vite :
GET /auth/oauth2renvoie une redirection vers l'IdP → l'instance est en mode IdP, utiliseroidc.POST /loginavec de bonnes identités renvoie « Invalid email or password » → il n'y a pas de compte local correspondant, utiliseroidc.les deux se négocient →
localest plus simple, l'utiliser.
Utilisation avec podman-compose
Une seule image, les deux variantes changent uniquement HEDGEDOC_READ_ONLY
(exemple de composition, à adapter à votre registre) :
{% for v in librechat_mcp_servers.hedgedoc.variants %}
mcp-hedgedoc-{{ v }}:
image: ghcr.io/votre-org/mcp-hedgedoc:latest
container_name: mcp-hedgedoc-{{ v }}
environment:
- HEDGEDOC_URL={{ hedgedoc_addr }}
- HEDGEDOC_AUTH_MODE=local
- HEDGEDOC_EMAIL={{ mcp_hedgedoc_bot_email }}
- HEDGEDOC_PASSWORD={{ mcp_hedgedoc_bot_password }}
- HEDGEDOC_READ_ONLY={{ 'true' if v == 'ro' else 'false' }}
- REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-bundle.crt
volumes:
- /etc/ssl/certs/ca-bundle.crt:/etc/ssl/certs/ca-bundle.crt:ro
restart: unless-stopped
{% endfor %}Construire et publier l'image
L'image est publiée sur GHCR par la CI GitHub Actions (voir
.github/workflows/ci.yml) : tag immuable par commit, plus latest sur
la branche par défaut. Pour construire et pousser manuellement :
podman build -t ghcr.io/votre-org/mcp-hedgedoc:latest -f Containerfile .
podman login ghcr.io
podman push ghcr.io/votre-org/mcp-hedgedoc:latestVérifier une image après construction
scripts/smoke_test.sh ghcr.io/votre-org/mcp-hedgedoc:latestLance le conteneur en mode lecture seule contre une URL bidon, vérifie que
les 6 outils de lecture apparaissent et que create_note et
update_note sont bien rejetés — sans jamais toucher à une vraie
instance HedgeDoc. Voir le script pour le détail.
update_note et le canal temps réel
update_note est le seul outil d'écriture qui ne passe pas par HTTP :
HedgeDoc 1.x n'ayant aucun endpoint de mise à jour, il pilote le canal
Socket.IO de l'éditeur (protocole vérifié source, HedgeDoc 1.10.8) :
connexion à l'espace de la note (?noteId=… dans le handshake, cookie
de session transmis en header), réception de l'état doc, émission de
l'opération OT « supprimer tout + insérer le nouveau contenu », attente
de l'ack.
Deux propriétés importantes à connaître :
l'
ack≠ « sauvegardé en base ». Le serveur ack dès que l'opération est appliquée en mémoire ; la persistance est faite par une boucle de 1 seconde. C'est pourquoi l'outil relit la note par HTTP (GET /download) en polling et ne renvoieverified: trueque quand le contenu lu correspond réellement à la base de données.les permissions sont appliquées par HedgeDoc, pas ici.
freely→ tout le monde ;editable/limited→ utilisateur connecté ;locked/private/protected→ propriétaire uniquement. En cas de refus, HedgeDoc n'envoie niackni erreur : l'outil échoue après timeout en le signalant clairement.
L'identité reste celle du compte de service partagé : toute modification apparaît sous ce compte dans l'historique HedgeDoc.
Tests
pip install -e ".[dev]"
pytest44 tests, tous hors-réseau (mocks HTTP via responses, page IdP
synthétique pour le scraping OIDC, et un serveur Socket.IO réel en
boucle locale pour le chemin temps réel d'update_note) sauf le smoke
test du conteneur ci-dessus, qui est volontairement séparé du reste.
Voir aussi
AGENTS.md pour les conventions du dépôt (comment ajouter un outil,
pourquoi certains choix ont été faits) et les limitations connues de
HedgeDoc 1.x sur lesquelles ce projet s'appuie.
Licence
GPL-3.0-or-later — voir LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Interact with your HackMD notes and teams seamlessly. Manage your notes, view reading history, and…
Encrypted Markdown notes and team knowledge base. Search, read and write notes in vaults you allow.
MCP-native open-source Notion alternative: read & write pages, databases and kanban boards.
Search and read your own notes: insights, drafts, book and podcast notes. Read-only, OAuth.
Related MCP Servers
- AlicenseBqualityCmaintenanceEnables interaction with HackMD via its API to manage personal and team notes. It supports listing, reading, creating, updating, and deleting notes, as well as accessing user history and profile information.122 npmMIT
- AlicenseAqualityDmaintenanceEnables creating, reading, and managing HedgeDoc 1.x notes and Mermaid diagrams from AI agents via the MCP protocol.111MIT
- FlicenseNot gradedqualityDmaintenanceEnables listing, reading, and writing notes with automatic version snapshots before edits, secured by token authentication.-
- AlicenseAqualityBmaintenanceMCP server for interacting with self-hosted HedgeDoc 1.x, enabling AI agents to create, read, update, and manage notes via session-cookie authentication with automatic re-login.51MIT