Hackmd MCP

What yuna0x0/hackmd-mcp does

The yuna0x0/hackmd-mcp MCP server gives AI clients access to HackMD account and content operations through the HackMD API. It covers authenticated user information, teams available to that user, reading history, and notes owned by the user or associated with a team.

Note operations include retrieving a note by ID and creating, updating, or deleting notes. Separate team-note tools support listing and modifying notes in a team. This makes the server suitable for workflows such as finding existing documentation, drafting a new HackMD note, revising shared team content, or removing obsolete notes.

The project is listed in the Workplace & Productivity category and requires a HackMD API token for all operations.

How it works

MCP clients call the exposed tools, and the server makes corresponding requests to the HackMD API. The available tools are grouped around profiles, teams, history, team notes, and user notes. The server supports both STDIO and HTTP transports.

For local use, an MCP client starts the package with Node.js and communicates over STDIO. For service deployment, the HTTP entry point can be started with pnpm and listens on port 8081 by default. The port can be changed with the PORT environment variable.

HTTP deployments can receive configuration from environment variables or request headers. A token supplied through the Hackmd-Api-Token header takes precedence over the server-level HACKMD_API_TOKEN value. If an HTTP server has a token preconfigured, its endpoint should be protected with authentication before being exposed to users.

Setup and configuration

The yuna0x0/hackmd-mcp MCP server requires Node.js 18 or later and a HackMD API token. Create the token from HackMD settings, then provide it through the client configuration or environment. A typical STDIO setup starts the package with npx -y hackmd-mcp and sets HACKMD_API_TOKEN.

HACKMD_API_URL is optional and defaults to https://api.hackmd.io/v1. For HTTP hosting, ALLOWED_HACKMD_API_URLS can restrict which API URLs the server accepts; when unset, only the default URL is allowed. HTTP clients may instead provide Hackmd-Api-Token and Hackmd-Api-Url headers.

For development, clone the repository, install dependencies with pnpm, and copy env.example to .env. The MCP Inspector can be used to connect to the running server, browse tools, submit test parameters, and inspect responses. A Docker image is also published through GitHub Container Registry.

Tools and capabilities

The server exposes these operations:

• Get authenticated user information with get_user_info.
• List accessible teams with list_teams.
• Read account history with get_history.
• List, create, update, and delete team notes with the team-note tools.
• List notes owned by the user with list_user_notes.
• Retrieve a specific note with get_note.
• Create, update, and delete user notes with the corresponding note tools.

The tools can support requests such as listing personal notes, showing available teams, creating meeting notes, or updating shared team documentation.

Limitations and notes

The material does not document permission behavior for individual notes or teams beyond access through the authenticated HackMD account.

HTTP hosting introduces an additional security concern: anyone who can reach an endpoint with a preconfigured token may be able to use that token unless the deployment adds authentication. Keep tokens out of source control and protect .env files, environment variables, and HTTP headers.

The documented default HTTP port is 8081, while the API URL and port can be changed through configuration. No additional note search, sharing, export, or revision-history tools are documented.