HackMD MCP Server for Collaborative Markdown Editing

Overview

The HackMD MCP Server exposes HackMD/CodiMD documents through the Model Context Protocol (MCP), enabling language models and other MCP-aware clients to create, read, and update collaborative Markdown notes programmatically. By bridging HackMD’s notes API with the MCP tool pattern, this server makes document content available as model context and allows model-driven tooling to modify or generate Markdown collaboratively.

This is useful when you want an AI assistant (or any MCP-capable tool) to interact with shared Markdown documents in HackMD: for example, generating a meeting summary into a new note, updating a draft with model-suggested edits, or retrieving the latest document text for context-aware responses. Developers can run the server locally or in production, configure credentials for their HackMD instance, and use the MCP tool endpoints to manage notes.

Features

• MCP-compatible tool endpoints that map to HackMD note operations
• Create new HackMD notes (title + content)
• Read note metadata and Markdown content
• Update existing notes (replace or append content)
• Simple configuration via environment variables or .env file
• Docker-friendly for quick deployment

Installation / Configuration

Prerequisites: Node.js (16+), npm, and a HackMD/CodiMD instance with an API token (or credentials allowed by your HackMD instance).

Clone and install

git clone https://github.com/yuna0x0/hackmd-mcp.git
cd hackmd-mcp
npm install

Environment variables

Create a .env file or export environment variables required by the server. Example .env:

# Base URL of your HackMD or CodiMD instance (no trailing slash)
HACKMD_BASE_URL=https://hackmd.example.com

# API token or personal access token for HackMD with note read/write scope
HACKMD_TOKEN=your_hackmd_api_token

# TCP port for the MCP server to listen on
PORT=3000

# Optional: prefix for MCP tool endpoints (default: /tools)
MCP_PREFIX=/tools

Run locally

npm start
# or for development with auto-reload
npm run dev

Docker (build & run)

# build image
docker build -t hackmd-mcp .

# run container, expose port and pass env vars
docker run -d --name hackmd-mcp \
  -e HACKMD_BASE_URL=https://hackmd.example.com \
  -e HACKMD_TOKEN=your_hackmd_api_token \
  -e PORT=3000 \
  -p 3000:3000 \
  hackmd-mcp

Notes about authentication

• Provide a HackMD API token capable of creating and editing notes. If your HackMD is self-hosted, ensure the instance allows API access for that token.
• Secure the MCP server itself in production (e.g., network rules, TLS, or an authentication proxy) because it performs write operations to your HackMD instance.

Available Tools / Resources

The server exposes a small set of MCP-style tools that map to common HackMD note operations. Endpoint paths can be prefixed via MCP_PREFIX; replace HOST and PORT with your deployment values.

• Create note
  • POST {HOST}:{PORT}{MCP_PREFIX}/hackmd.create
  • Request JSON: { “title”: “My Title”, “content”: “# Hello\nWorld”, “visibility”: “public|private” }
  • Response JSON: { “noteId”: “”, “url”: “”, “createdAt”: “…” }
  • Read note
    • POST {HOST}:{PORT}{MCP_PREFIX}/hackmd.read
    • Request JSON: { “noteId”: “” }
    • Response JSON: { “noteId”: “”, “title”: “…”, “content”: “…”, “updatedAt”: “…” }
    • Update note
      • POST {HOST}:{PORT}{MCP_PREFIX}/hackmd.update
      • Request JSON: { “noteId”: “”, “content”: “…”, “mode”: “replace|append” }
      • Response JSON: { “noteId”: “”, “updatedAt”: “…” }

        These tool endpoints follow a predictable JSON request/response shape so MCP-aware clients and LLM

        Tags:developer-tools