HackMD
About
A Model Context Protocol server for integrating [HackMD](https://hackmd.io)'s note-taking platform with AI assistants.
Details
- Author
- yuna0x0
- GitHub stars
- 64
- Downloads
- 467
- Categories
- Productivity, Community, Other, API, AI
Jump to
- Retrieve authenticated user profile information
- Create, read, update, and delete HackMD notes
- Manage team notes and collaborate with team members
- Access user reading history and list teams
- Dual transport support: HTTP and STDIO
- Cloud‑deployment ready (Smithery and others)
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
HackMDCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Install the server by adding it to your MCP client configuration (e.g., mcp.json or claude_desktop_config.json) with the command npx -y hackmd-mcp and setting the environment variable HACKMD_API_TOKEN. You may optionally set HACKMD_API_URL for a different API endpoint. For self‑hosted HTTP transport, run pnpm run start:http (default port 8081, configurable via PORT). Cloud deployment is supported via platforms like Smithery.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"hackmd": {
"hackmd": {
"command": "npx",
"args": [
"-y",
"hackmd-mcp"
],
"env": {
"HACKMD_API_TOKEN": "your_api_token"
}
}
}
}
}McpServers
{
"hackmd": {
"command": "npx",
"args": [
"-y",
"hackmd-mcp"
],
"env": {
"HACKMD_API_TOKEN": "your_api_token"
}
}
}HackMD MCP Server
A Model Context Protocol (MCP) server that interfaces with the HackMD API, allowing LLM clients to access and interact with HackMD notes, teams, user profiles, and history data.
Features
- Get user profile information
- Create, read, update, and delete notes
- Manage team notes and collaborate with team members
- Access reading history
- List and manage teams
- Dual transport support: Both HTTP and STDIO transports
- Cloud deployment ready: Support Smithery and other platforms
Requirements
- Node.js 18+
Local Installation (STDIO Transport)
1. Add this server to your mcp.json / claude_desktop_config.json:
{
"mcpServers": {
"hackmd": {
"command": "npx",
"args": ["-y", "hackmd-mcp"],
"env": {
"HACKMD_API_TOKEN": "your_api_token"
}
}
}
}
You may also optionally set the HACKMD_API_URL environment variable if you need to use a different HackMD API endpoint.
2. Restart your MCP client (e.g., Claude Desktop)
3. Use the tools to interact with HackMD
Server Deployment (HTTP Transport)
Self-Hosting
Follow the Local Development instructions to set up the project locally, then run:pnpm run start:http
PORT environment variable.
Cloud Deployment
You can deploy this MCP server to any cloud platform that supports Node.js server applications.
You can also deploy via MCP platforms like Smithery.
Configuration
Environment Variables (STDIO Transport and HTTP Transport server where host provides the config)
When using the STDIO transport or hosting the HTTP transport server, you can pass configuration via 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 applied only for the HTTP transport server:
- ALLOWED_HACKMD_API_URLS: (Optional) A comma-separated list of allowed HackMD API URLs. The server will reject requests if the provide HackMD API URL is not in this list. If not set, only the default URL (https://api.hackmd.io/v1) is allowed.
> [!CAUTION]
> If you are hosting the HTTP transport server with token pre-configured, you should protect your 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 where user provides the config)
When using the HTTP transport, user can pass configuration via 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 the token in the header, while the server also has HACKMD_API_TOKEN set, the header value will take precedence.
Get a HackMD API Token
To get an API token, follow these steps:
1. Go to HackMD settings.
2. Click on "Create API Token".
3. Copy the generated token and use it in your .env file or environment variables.
Available Tools
Profile Tools
- get_user_info: Get information about the authenticated userTeams Tools
- list_teams: List all teams accessible to the userHistory Tools
- get_history: Get user's reading historyTeam Notes 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 teamUser Notes Tools
- list_user_notes: List all notes owned by the user - get_note: Get a note by its ID - create_note: Create a new note - update_note: Update an existing note - delete_note: Delete a noteExample Usage
Basic Note Management
Can you help me manage my HackMD notes?
List Notes
Please list all my notes.
Create a New Note
`
Create a new note with the title "Meeting Notes" and content:
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
