hedgedoc-mcp
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.
hedgedoc-mcp
An MCP server that lets an agent read and edit live HedgeDoc 1.x notes without dropping a human's typing on the floor.
HedgeDoc 1.x has no supported document write API. Every edit goes over its live OT socket (operational transformation, which merges concurrent edits), so an agent that reads a note, thinks for a minute, and writes the whole document back will erase whatever a person typed in between.
This server sits between the agent and that socket. It gives the agent ordinary
read and edit tools, and every write carries the revision it was based on
(rev, the note's edit counter) and the content hash (hash, a digest of the
note text). If the note moved, the write is refused and nothing is sent. By
default, if it lands, the server reads the edited region back through
HedgeDoc's download endpoint before reporting success.
It was built for LINUX Unplugged show notes, where two hosts and an agent work on the same document before a show. Nothing in it is specific to that show, and it targets any HedgeDoc 1.12 note your account can edit.
Unofficial client. Not affiliated with or endorsed by the HedgeDoc project.
Status
Item | State |
Version |
|
HedgeDoc 1.12 | Tested |
HedgeDoc 1.11 | Expected to work, not exercised yet |
HedgeDoc 1.10 and older | Refused at connect (they use Socket.IO 2) |
HedgeDoc 2 | Not supported |
Install | Nix is supported today; the npm package is not published yet |
Related MCP server: agent-notes-mcp
Requirements
A HedgeDoc 1.12 instance, reachable over HTTP or HTTPS. 1.11 should work but has not been exercised yet.
A registered account that can edit the target note. Use a dedicated bot account, not a person's login.
The note id, which is the last path segment of the note URL.
Node 20 or newer, or Nix.
You do not need shell access to the HedgeDoc host, a server-side plugin, or a database connection.
Install
Nix
nix run github:noblepayne/hedgedoc-mcp
nix profile install github:noblepayne/hedgedoc-mcpThe flake package carries Node, the compiled server, and a hedgedoc-mcp
binary that starts the multi-note supervisor.
From source
The npm package is not published yet, so npm install -g hedgedoc-mcp does not
work today. Build it from a clone instead:
git clone https://github.com/noblepayne/hedgedoc-mcp
cd hedgedoc-mcp
npm install
npm run build
node hedgedoc_mcp/multi.mjsnpm run build is npx squint compile, which writes hedgedoc_mcp/*.mjs from
src/hedgedoc_mcp/*.cljs. The compiled output needs Node 20 or newer, and the
start script runs the same entry point.
Configure
The server takes settings from the environment and nothing else. Point it at an instance and a note, then give your MCP client a stdio entry.
OpenCode, in a project opencode.json or the global config:
{
"mcp": {
"hedgedoc": {
"type": "local",
"command": ["hedgedoc-mcp"],
"environment": {
"HEDGEDOC_URL": "https://hedgedoc.example.com",
"HEDGEDOC_EMAIL": "bot@example.com",
"HEDGEDOC_PASSWORD": "…",
"HEDGEDOC_NOTE_ID": "<note-id>"
}
}
}
}Claude Desktop and other clients that use mcpServers:
{
"mcpServers": {
"hedgedoc": {
"command": "hedgedoc-mcp",
"env": {
"HEDGEDOC_URL": "https://hedgedoc.example.com",
"HEDGEDOC_EMAIL": "bot@example.com",
"HEDGEDOC_PASSWORD": "…",
"HEDGEDOC_NOTE_ID": "<note-id>"
}
}
}
}Restart the client after adding the entry. The tools appear under the server name you chose.
HEDGEDOC_NOTE_ID sets a default note. You can omit it and pass note-id on
every call instead, which is useful when the agent should not have a default
target. Set HEDGEDOC_MAX_NOTES to cap how many notes one server process may
open.
Variables
Variable | Required | Notes |
| yes | Instance URL. A subpath such as |
| no | Default note. Required by the single-note |
| auth | Preferred. The server logs in and refreshes the session. |
| auth | Full cookie pair, |
| no |
|
| no |
|
| no | Budget for confirming a write, in ms. Default 10000. |
| no | Poll interval, in ms. Default 500. |
| no | Worker cap in the multi-note binary. Default 32. |
| no | Presence idle threshold, in ms. Default 30000. |
| no | Allow writes over a guest session. Most HedgeDoc 1.12 instances still refuse the room join. |
| no | Expose the gated whole-document replace tool. |
Auth is email plus password, a session cookie, or a guest session for reads. Guest writes are best effort: on 1.11 and 1.12 a guest usually cannot join the OT room, so use a registered bot account for edits.
First edit
Start the client and give the agent the note id. A useful first prompt:
Use the
hedgedoctools for note<note-id>. Callget-statusuntil the rev is no longer -1, read the section you want to change, and dry-run a line edit. Show me the preview and do not write until I say so.
The first get-status can return rev: -1 and connected: false while the
server logs in and joins the note. Call it again after a second. Once the rev is
a number, the session is ready.
A dry run returns a window of numbered lines around the edit and writes nothing.
The example is abridged. The full result also carries would-be-hash,
preview-lines, and ops, and it has no new-rev because nothing was emitted.
{
"dry-run": true,
"status": "dry-run",
"written": false,
"base-rev": 4,
"base-hash": "ab23c794…",
"preview": "72 | the line before\n73 | the edited line\n74 | the line after",
"hint": "no write was emitted; rev and hash are the current base"
}If the preview looks right, call the same tool with dryRun: false. A write that
lands reports how the server checked it:
{
"status": "confirmed",
"verified": "download-poll",
"new-rev": 5,
"new-hash": "dc19bc80…"
}The full result adds preview, via, and op-id.
| Meaning |
| The edited region was read back from HedgeDoc's |
|
|
A timeout is status: applied-but-unconfirmed, not success: the op may have
landed. Re-read the note and decide from there.
How writes are gated
Compare and swap (CAS) inside the server
Every write takes base-rev and base-hash from a fresh read. Before emitting,
the server compares both against its current view of the note. If either moved,
the write is refused with the current values and nothing goes out. The wire
protocol has no base-hash, so the comparison happens inside this server; the
/download poll is the durability check.
One emit per write
If the poll cannot confirm the write, the tool says so and stops. A timeout is
applied-but-unconfirmed, not proof that the first op failed, so it is not
retried automatically. Retries are only for failures that happen before the op
leaves the socket. Re-read and decide.
Per-socket revisions
A reconnect invalidates the local revision, and writes are refused with
rev-unknown until a doc frame supplies the new one. After a resync the server
rejoins; it does not guess the revision.
Serialized writes
A second write on the same note while one is running is rejected with
emit-in-flight. Wait for the first to finish.
One worker per note
The default binary runs an isolated core process for each note, so notes do not share a socket, revision state, or in-flight write.
Tools
Tool | What it does |
| Reports revision, hash, headings, idle time, rev velocity, auth kind, and connection state. |
| Returns one heading's content with UTF-16 offsets. |
| Returns the note, or a page of lines, with front matter and heading line numbers. |
| Writes raw ops under CAS, or replaces a section body via |
| Inserts a block at the end of a section, before the next heading. |
| Applies batch 1-based line edits with an |
| Inserts before a line. |
| Deletes a line range, one line by default. Refuses to run past the end of the note. |
| Searches lines by substring or regex, case insensitive by default. |
| Reports users and selection data, advisory only; the gate is the pre-emit overlap check inside |
| Lists notes with a live worker, plus the default note. |
| Replaces the whole document under the gate; only with |
Arguments
Argument | Tools | Notes |
| Every tool except | Selects the worker. The single-note |
| Every write | Taken from a fresh read. A stale base is refused. |
| Write tools | Returns the preview window with |
| Write tools |
|
|
| Aliases: |
|
| Required. |
Use the camelCase names. The older spellings still parse, so clients written
against 0.2.0 keep working, and a conflict between an alias and its canonical
spelling is rejected as bad-args.
Typical loop: get-status, then read-note or read-section, then a dry run,
then the write. On stale-revision, read again and use the new rev and hash. On
applied-but-unconfirmed, re-read before doing anything else.
Troubleshooting
Result | What to do |
| The worker is still booting. Call |
| The socket reconnected. Call |
| The socket is down. Retry after a second. |
| The note moved. Read again and use the new rev and hash. |
| The |
| Re-read before doing anything else. Do not re-emit blindly. |
| Another write is running. Wait for it to finish. |
| You are a guest. Use the bot account. |
401 or | Check the email, password, or cookie. |
| The write would pass 100 KB. Split it or edit a smaller region. |
| Check |
Limits
CAS runs inside this server. The wire protocol has no
base-hash, so the gate compares against the local copy this server keeps.A write whose result would exceed 100 KB is refused. Larger notes can still be read.
ATX headings and backtick fences are recognized. Setext headings and
~~~fences are not.There is no undo. HedgeDoc's own history is the recovery path.
HedgeDoc 2 is not supported.
searchwithregex: trueuses JavaScript's backtracking engine. A pathological pattern on a very long line can block the worker; the multi-note supervisor recycles it after 180 seconds. Prefer substrings for untrusted patterns.
Security
Use a dedicated bot account with edit rights only on the notes it needs. Do not use a person's primary login.
Passwords are not logged. Logs carry note ids, revisions, error codes, the target URL, and the account display name.
The server speaks stdio. It does not listen on a port.
set-noteis off unless explicitly enabled, and requiresforceandreason.Rotate the bot password if it leaks.
Development
npm install
npm run build
npm run test:pbt
node test/snapshot-gc.mjs
node test/retry-safety.mjs
node test/remote-op-fold.mjs
node test/bin-launch.mjs
node test/arg-validation.mjs
./scripts/e2e.sh
nix flake checkscripts/e2e.sh brings up a disposable HedgeDoc with
podman-compose if 127.0.0.1:3000/status is not already answering, registers
bot@dev.local, and needs open registration on the instance. Set HEDGEDOC_URL
to use an existing dev instance instead.
nix flake check builds the package and runs the version check, property tests,
GC, retry, remote-op, launcher, and argument validation suites from
package.nix. It checks the current system; pass --all-systems only when
builders for the other systems are configured.
AGENT_SCENARIOS.md has the scenario suite in prompt
form, and test/agent-scenarios.mjs automates it. CONTRIBUTING.md covers the
gate and the write-path rules; docs/PROTOCOL.md records
the wire facts.
License
MIT, see LICENSE. HedgeDoc itself is AGPL and runs as a separate
process.
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
Read and write a CRM built for agents. Every change carries who asserted it and how.
Private living HTML pages agents publish, recall, update, and share at name.notepad.page.
Search, read, and safely update Markdown notes in your connected Phasoric knowledge vaults.
Publish your agent's Markdown as shareable web pages with revision provenance and comments.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables creating, reading, and managing HedgeDoc 1.x notes and Mermaid diagrams from AI agents via the MCP protocol.111MIT
- AlicenseNot gradedqualityCmaintenanceLets MCP clients search, read, create, append, replace, move, and batch-update local Markdown notes safely, with conflict detection via SHA-256 and optional managed update blocks, without requiring a vector database.MIT
- AlicenseNot gradedqualityCmaintenanceEnables safe, reviewable updates to HackMD notes by preparing diffs locally, requiring explicit approval before writing, and verifying the result after the update.MIT
- AlicenseBqualityCmaintenanceEnables AI agents to search and read linked Markdown notes, queue review questions, capture feedback, and propose edits with stale-edit protection.7Apache 2.0