Content
# HedgeDoc MCP Server
[MCP](https://modelcontextprotocol.io/) server for **HedgeDoc 1.x** — the open-source collaborative markdown editor.
Create notes and Mermaid diagrams from OpenCode and other MCP-compatible AI agents.
> **Note:** This is built for HedgeDoc **1.x** (formerly CodiMD).
> It uses the [HedgeDoc 1.x API](https://docs.hedgedoc.org/dev/api/), which differs from HedgeDoc 2.
## Tools
| Tool | Description |
|---|---|
| `hedgedoc_create_blank` | Create a blank note with the instance's default template |
| `hedgedoc_create` | Create a new note with a random ID |
| `hedgedoc_create_with_alias` | Create a new note with a custom URL alias (requires [FreeURL mode](https://docs.hedgedoc.org/references/url-scheme/#freeurl-mode)) |
| `hedgedoc_create_diagram` | Create a note with a [Mermaid](https://mermaid.js.org/) diagram |
| `hedgedoc_read` | Read the raw markdown content of a note |
| `hedgedoc_info` | Get note metadata (title, description, timestamps, viewcount) |
| `hedgedoc_list_revisions` | List all available revisions of a note |
| `hedgedoc_get_revision` | Get the full content of a specific revision |
| `hedgedoc_publish_url` | Get the published (read-only) URL of a note |
| `hedgedoc_slide_url` | Get the slide presentation URL of a note |
| `hedgedoc_status` | Get the current status of the HedgeDoc instance |
## Usage
```bash
export HEDGEDOC_URL="https://hedgedoc.your-instance.com"
uvx hedgedoc-mcp-server stdio
```
HedgeDoc 1.x does **not** use API tokens for note operations. Authentication is handled via
session cookies (browser) or instance configuration
([see Production Ready guide](https://docs.hedgedoc.org/guides/production-ready/)).
### OpenCode config
```jsonc
{
"mcp": {
"hedgedoc": {
"type": "local",
"enabled": true,
"command": ["uvx", "hedgedoc-mcp-server", "stdio"],
"environment": {
"HEDGEDOC_URL": "https://hedgedoc.your-instance.com"
}
}
}
}
```
### Requirements
| Requirement | Notes |
|---|---|
| HedgeDoc 1.x instance | Tested on 1.x. Not compatible with HedgeDoc 2. |
| Python 3.11+ | |
| `uv` (recommended) | Or `pip install hedgedoc-mcp-server` |
## API Endpoints Used
This server uses the following [HedgeDoc 1.x API](https://docs.hedgedoc.org/dev/api/) endpoints:
| Method | Endpoint | Used by |
|---|---|---|
| `GET` | `/new` | Create a blank note |
| `POST` | `/new` | Create a note (random ID) |
| `POST` | `/new/{alias}` | Create a note (custom alias) |
| `GET` | `/{id}/download` | Read raw markdown |
| `GET` | `/{id}/info` | Read metadata |
| `GET` | `/{id}/revision` | List revisions |
| `GET` | `/{id}/revision/{rev}` | Get specific revision |
| `GET` | `/{id}/publish` | Published URL |
| `GET` | `/{id}/slide` | Slide URL |
| `GET` | `/status` | Instance status |
For more details, see the [official API docs](https://docs.hedgedoc.org/dev/api/).
## Instance Configuration
Your HedgeDoc administrator may need to configure these settings:
| Setting | Impact | Docs |
|---|---|---|
| `CMD_ALLOW_ANONYMOUS=true` | Allows note creation without login | [Users and Privileges](https://docs.hedgedoc.org/configuration/#users-and-privileges) |
| `CMD_ALLOW_FREEURL=true` | Enables custom URL aliases | [Users and Privileges](https://docs.hedgedoc.org/configuration/#users-and-privileges) |
| `CMD_RATE_LIMIT_NEW_NOTES=20` | Max new notes per 5 minutes (default: 20) | [Web Security](https://docs.hedgedoc.org/configuration/#web-security-aspects) |
| `CMD_DOCUMENT_MAX_LENGTH=100000` | Max note length in chars (default: 100k) | [HedgeDoc basics](https://docs.hedgedoc.org/configuration/#hedgedoc-basics) |
| `CMD_DISABLE_NOTE_CREATION=false` | If true, no notes can be created | [Users and Privileges](https://docs.hedgedoc.org/configuration/#users-and-privileges) |
## Development
```bash
git clone https://github.com/Jyzus/kaymer-hedgedoc-mcp
cd kaymer-hedgedoc-mcp
uv venv && uv pip install -e .
HEDGEDOC_URL="https://hedgedoc.your-instance.com" uv run hedgedoc-mcp-server
```
## License
MIT
