hackmd-mcp is a Model Context Protocol (MCP) server used to integrate the HackMD note platform with AI assistants. Through the HackMD API, it allows LLM clients to access and operate on HackMD notes, teams, user profiles, and historical data.
Main capabilities
This server provides the following tools:
- get_user_info: Get information about the authenticated user
- list_teams: List all teams accessible to the user
- get_history: Get the user's reading history
Team note tools:
- list_team_notes: List all notes in a team
- create_team_note: Create a new note in a team
- update_team_note: Update an existing note in a team
- delete_team_note: Delete a note in a team
User note tools:
- list_user_notes: List all notes owned by the user
- get_note: Get a note by ID
- create_note: Create a new note
- update_note: Update an existing note
- delete_note: Delete a note
Usage
Local installation (STDIO transport)
Add this server to mcp.json / claude_desktop_config.json, and optionally set the HACKMD_API_URL environment variable to use a different HackMD API endpoint. After restarting the MCP client (such as Claude Desktop), you can use the tools to interact with HackMD.
Server deployment (HTTP transport)
Set up the project locally according to the local development instructions, then run the server. The default port is 8081, and the port can be changed via the PORT environment variable.
Cloud deployment
This MCP server can be deployed to any cloud platform that supports Node.js server applications, and can also be deployed through MCP platforms such as Smithery.
Environment variables
When using STDIO transport or hosting an HTTP transport server, configuration can be passed through environment variables:
- HACKMD_API_TOKEN: HackMD API Token (required for all operations)
- HACKMD_API_URL: (optional) HackMD API URL, defaults to https://api.hackmd.io/v1
Environment variables only applicable to the HTTP transport server:
- ALLOWED_HACKMD_API_URLS: (optional) A comma-separated list of allowed HackMD API URLs. If the provided HackMD API URL is not in the list, the server will reject the request. If not set, only the default URL is allowed.
If you host an HTTP transport server with a preconfigured token, you should protect the endpoint and implement authentication before allowing users to access it, otherwise anyone can access your MCP server while using your HackMD token.
HTTP headers (HTTP transport with user-provided configuration)
When using HTTP transport, users can pass configuration through HTTP headers:
- Hackmd-Api-Token: HackMD API Token (required for all operations)
- Hackmd-Api-Url: (optional) HackMD API URL, defaults to https://api.hackmd.io/v1
If the user provides a token in the header and the server also has HACKMD_API_TOKEN set, the value in the header takes precedence.
Getting a HackMD API Token
- Go to HackMD settings.
- Click "Create API Token".
- Copy the generated token and use it in the .env file or environment variables.
Applicable scenarios
Suitable for scenarios that require integrating the HackMD note platform with AI assistants, such as managing notes through an LLM client, team collaboration, and accessing reading history.
Limitations
- A HackMD API Token is required for all operations.
- When using HTTP transport, if the server has a preconfigured token, you need to implement authentication yourself to protect the endpoint.
- The project uses the MIT license.
Local development
The project uses pnpm as the package manager. Clone the repository and install dependencies, copy the example to create a .env file, edit the .env file and add the HackMD API token.
You can use MCP Inspector to test and debug the HackMD MCP server. Open a browser and visit the provided URL (usually http://localhost:6274）即可访问 MCP Inspector interface, connect to the server, browse available tools, run tools with custom parameters, and view responses.
Docker-related: pull from GitHub Container Registry, or perform local development builds and multi-platform builds.
MCP Bundles (MCPB): run commands to create an MCP Bundle.
Security Notice
This MCP server accepts the HackMD API token in a .env file, environment variables, or HTTP headers. Please keep the information secure and never commit it to version control.
