hackmd

The HackMD MCP Server provides an interface to HackMD APIs through the MCP (Model Context Protocol) framework. It exposes tools to access and manage HackMD data such as user profiles, notes (create/read/update/delete), team notes, teams, and reading history. It supports both STDIO and HTTP transports, allowing you to connect from local MCP clients or host an HTTP API server for remote usage. Available tools include get_user_info, list_teams, get_history, list_team_notes, create_team_note, update_team_note, delete_team_note, list_user_notes, get_note, create_note, update_note, and delete_note. When using the HTTP transport, you can configure the endpoint and authentication via headers, while the STDIO transport relies on environment variables.

Prerequisites:

• Node.js 18+ installed
• pnpm package manager (recommended)

Local installation (STDIO transport):

1. Clone the repository and install dependencies:

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

2. Create and configure your environment:

cp env.example .env

Edit .env to set HACKMD_API_TOKEN with your HackMD API token.

3. Run the server via npx (STDIO transport):

npx -y hackmd-mcp

Configuration in MCP client (example mcp.json):

{
  "mcpServers": {
    "hackmd": {
      "command": "npx",
      "args": ["-y", "hackmd-mcp"],
      "env": {
        "HACKMD_API_TOKEN": "your_api_token"
      }
    }
  }
}

HTTP transport deployment (self-hosting):

1. Install dependencies and build as needed, then start the HTTP transport server (port 8081 by default) with your token in environment variables:

PORT=8081 HACKMD_API_TOKEN=your_api_token pnpm run start:http

2. Optionally set HACKMD_API_URL to point to a specific HackMD API endpoint and ALLOWED_HACKMD_API_URLS to restrict endpoints.

HACKMD_API_URL=https://api.hackmd.io/v1 ALLOWED_HACKMD_API_URLS=https://api.hackmd.io/v1

Docker deployment (optional):

docker pull ghcr.io/yuna0x0/hackmd-mcp

Tips and notes:

• Always protect your HackMD API token. If hosting via HTTP transport, restrict access and consider adding authentication on your endpoint.
• If you set HACKMD_API_URL, you may also configure ALLOWED_HACKMD_API_URLS to restrict which endpoints are usable.
• The HTTP transport uses headers Hackmd-Api-Token and Hackmd-Api-Url; header values take precedence over environment variables if both are provided.
• The token is used for all operations; without a valid token, requests will fail.
• For local testing with the MCP Inspector, you can run the inspector with npx @modelcontextprotocol/inspector -e HACKMD_API_TOKEN=your_api_token npx hackmd-mcp or use pnpm run inspector in development workflows.
• The default HTTP port can be changed by setting PORT in the environment.
• If you modify the source, you can rebuild and redeploy using the standard pnpm build/run flows described in the repository README.