Skip to main content

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-mcp

Use 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 .

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)

Source distribution for hedgedoc-mcp 0.2.0
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)

Table of built distributions (wheels) for hedgedoc-mcp 0.2.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page