hedgedoc-mcp
An MCP server that lets AI agents — Claude Code, Codex, Hermes, or any MCP-compatible client — read and write notes on a self-hosted HedgeDoc 1.x instance.
HedgeDoc 1.x has no API token system, so this server handles the real auth model (session cookies from email/password login) and exposes it as a clean, agent-friendly toolset.
Why this exists
HedgeDoc is a great self-hosted, open-source, collaborative markdown editor. But if you want an AI agent to write notes to it programmatically, you hit a wall immediately: HedgeDoc 1.x has no API tokens. Every write endpoint (POST /new, etc.) requires an authenticated browser-style session, tracked via the Express session cookie configured by the instance (normally connect.sid).
This project does the unglamorous work of handling that correctly — login, cookie storage, automatic re-authentication on expiry — and wraps it in an MCP server so any agent can just call hedgedoc_create_note and not think about any of it.
Features
- 🔐 Handles HedgeDoc 1.x's real auth model (session cookies, not tokens)
- 🔁 Auto re-login on session expiry — no manual cookie refresh needed
- 🛠️ 5 MCP tools: create, read, info, whoami, history
- 🐍 Standalone Python client (
hedgedoc_mcp.client.HedgeDocClient) usable outside MCP too - ✅ Fully tested — against an in-process fake HedgeDoc server; no live instance required
- 📦 Works with any MCP client: Claude Code, Codex, Hermes, Cursor, custom clients
Quick start
1. Install
With uv (recommended — no venv management needed):
# Run directly without installing (uvx downloads + caches automatically)
uvx hedgedoc-mcp
# Or install as a persistent tool
uv tool install hedgedoc-mcp
Not yet on PyPI? Run straight from GitHub instead — same zero-install experience:
uvx --from git+https://github.com/mrsunglasses-experiments/hedgedoc-mcp hedgedoc-mcpUse this exact form in the agent config examples below (as
args) until the package is published.
With pip:
pip install hedgedoc-mcp
From source:
git clone https://github.com/mrsunglasses-experiments/hedgedoc-mcp.git
cd hedgedoc-mcp
uv pip install -e . # or: pip install -e .
2. Get a session cookie
HedgeDoc 1.x has no API tokens, so you authenticate once via the login endpoint and reuse the resulting session cookie:
hedgedoc-mcp-login --url https://md.example.com --email you@example.com --write-env .env
It prompts for your password (or reads HEDGEDOC_PASSWORD; avoid --password, which lands in your shell history), then prints HEDGEDOC_SESSION_COOKIE=... and, with --write-env, saves it to a file readable only by you.
The server does not read .env files itself — copy the value into your agent's MCP config (step 4), or load the file into your shell first (set -a; source .env; set +a).
Alternatively, set HEDGEDOC_EMAIL + HEDGEDOC_PASSWORD directly and the server will log in automatically on first use, re-authenticating whenever the session expires — no manual refresh needed.
3. Configure environment variables
export HEDGEDOC_URL=https://md.example.com
export HEDGEDOC_SESSION_COOKIE=s%3A... # from step 2, OR:
export HEDGEDOC_SESSION_COOKIE_NAME=connect.sid # only when your instance uses another name
export HEDGEDOC_EMAIL=you@example.com # for auto re-login
export HEDGEDOC_PASSWORD=your-password
At minimum you need HEDGEDOC_URL plus either the cookie or the email+password pair. Setting both is recommended — the cookie is used as a fast path, and email/password is the automatic fallback whenever it expires.
HEDGEDOC_SESSION_COOKIE_NAME defaults to connect.sid. Set it to the valid cookie name configured by your HedgeDoc instance (for example, hedgedoc.sid) so both login and manually supplied cookies use the right session.
4. Wire it into your agent
Claude Code
claude mcp add \
--env HEDGEDOC_URL=https://md.example.com \
--env HEDGEDOC_EMAIL=you@example.com \
--env HEDGEDOC_PASSWORD='your-password' \
hedgedoc -- uvx hedgedoc-mcp
Or, to share the server with your team, add it to the project's .mcp.json. That file is meant to be committed, so reference secrets with ${VAR} and let each person set them in their own environment:
{
"mcpServers": {
"hedgedoc": {
"command": "uvx",
"args": ["hedgedoc-mcp"],
"env": {
"HEDGEDOC_URL": "https://md.example.com",
"HEDGEDOC_EMAIL": "${HEDGEDOC_EMAIL}",
"HEDGEDOC_PASSWORD": "${HEDGEDOC_PASSWORD}"
}
}
}
}
Codex CLI
Add to ~/.codex/config.toml:
[mcp_servers.hedgedoc]
command = "uvx"
args = ["hedgedoc-mcp"]
env = { HEDGEDOC_URL = "https://md.example.com", HEDGEDOC_EMAIL = "you@example.com", HEDGEDOC_PASSWORD = "your-password" }
Hermes
Add an MCP server entry in your Hermes config with command: uvx, args: [hedgedoc-mcp], and the same environment variables. See the Hermes MCP docs for the exact config location on your install.
Any other MCP client
This is a standard stdio MCP server. Point your client at uvx hedgedoc-mcp (or the installed hedgedoc-mcp executable) with the environment variables above set, and it will discover the 5 tools automatically via the standard MCP list_tools handshake. Using uvx means the client never needs a separate install step — uv downloads and caches the package on first run.
Available tools
| Tool | Description |
|---|---|
hedgedoc_create_note |
Create a new note (optionally with a custom URL alias). Returns the note ID and URL. |
hedgedoc_read_note |
Fetch a note's raw markdown content by ID or alias. |
hedgedoc_note_info |
Get a note's title, description, view count, and timestamps. |
hedgedoc_whoami |
Verify the session is valid and show the logged-in user. |
hedgedoc_list_history |
List the logged-in user's recently viewed/pinned notes. |
There is no update tool: HedgeDoc 1.x has no HTTP endpoint for editing a note (see Known limitations), so write a note's full content when creating it.
Using the Python client directly
You don't need MCP to use this — the underlying client is a normal Python class:
from hedgedoc_mcp.client import HedgeDocClient
client = HedgeDocClient("https://md.example.com")
client.login(email="you@example.com", password="your-password")
result = client.create_note("# Research notes\n\nSome findings...")
print(result.url)
content = client.read_note(result.note_id)
info = client.note_info(result.note_id)
Known limitations
HedgeDoc 1.x's HTTP API is genuinely limited compared to newer forks — see docs/LIMITATIONS.md for the full rundown, including:
- No API tokens (session-cookie auth only)
- No HTTP note-update endpoint
- No delete endpoint over HTTP
These are constraints of the HedgeDoc 1.x server itself, not this client — the docs explain the workarounds this project uses and what genuinely isn't possible.
Development
git clone https://github.com/mrsunglasses-experiments/hedgedoc-mcp.git
cd hedgedoc-mcp
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
pytest # run tests (against an in-process fake HedgeDoc; no live server needed)
ruff check . # lint
ruff format --check . # formatting
See docs/ARCHITECTURE.md for how the auth flow and MCP layer fit together, and CONTRIBUTING.md for contribution guidelines.
License
MIT — see LICENSE.
Metadata
Release files for hedgedoc-mcp 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| hedgedoc_mcp-0.2.0.tar.gz | 109.9 kB | With provenance | Details for hedgedoc_mcp-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| hedgedoc_mcp-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for hedgedoc_mcp-0.2.0-py3-none-any.whl |
Total release size: 126.4 kB
Release files / hedgedoc_mcp-0.2.0.tar.gz
| Download URL | hedgedoc_mcp-0.2.0.tar.gz |
|---|---|
| Size | 109.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7db9a5baec0902365fe5a863b9551254e1a8ce427cc2ff877fede89cf04224ff
|
|
BLAKE2b-256 checksum How to use checksums |
565ee4db8f3882c912020b859b6f4cde30dfbf98158e21bae3e43b7150021aca
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 13, 2026.
Transparency logRelease files / hedgedoc_mcp-0.2.0-py3-none-any.whl
| Download URL | hedgedoc_mcp-0.2.0-py3-none-any.whl |
|---|---|
| Size | 16.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
81115a73fd63bde7578de14375031eb0abb75a5a219d2f92eef3b79bdf1674ba
|
|
BLAKE2b-256 checksum How to use checksums |
0858d8dfcefa340ddc494fab6268e958cbb3dc53a5a1e2879e592fc4dcf41517
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 13, 2026.
Transparency logSecurity for hedgedoc-mcp 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for hedgedoc_mcp-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 13, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.