HackMD MCP Server

1# HackMD MCP Server
2 
3A Model Context Protocol (MCP) server that interfaces with the [HackMD API](https://hackmd.io/@hackmd-api/developer-portal), allowing LLM clients to access and interact with HackMD notes, teams, user profiles, and history data.
4 
5## Features
6 
7- Get user profile information
8- Create, read, update, and delete notes
9- Manage team notes and collaborate with team members
10- Access reading history
11- List and manage teams
12- **Dual transport support**: Both HTTP and STDIO transports
13- **Cloud deployment ready**: Support Smithery and other platforms
14 
15## Requirements
16 
17- Node.js 18+
18 
19## Local Installation (STDIO Transport)
20 
211. Add this server to your `mcp.json` / `claude_desktop_config.json`:
22 
23```json
24{
25  "mcpServers": {
26    "hackmd": {
27      "command": "npx",
28      "args": ["-y", "hackmd-mcp"],
29      "env": {
30        "HACKMD_API_TOKEN": "your_api_token"
31      }
32    }
33  }
34}
35```
36 
37You may also optionally set the `HACKMD_API_URL` environment variable if you need to use a different HackMD API endpoint.
38 
392. Restart your MCP client (e.g., Claude Desktop)
403. Use the tools to interact with HackMD
41 
42## Server Deployment (HTTP Transport)
43 
44### Self-Hosting
45Follow the [Local Development](#local-development) instructions to set up the project locally, then run:
46```bash
47pnpm run start:http
48```
49This will start the server on port 8081 by default. You can change the port by setting the `PORT` environment variable.
50 
51### Cloud Deployment
52 
53You can deploy this MCP server to any cloud platform that supports Node.js server applications.
54 
55You can also deploy via MCP platforms like [Smithery](https://smithery.ai/server/@yuna0x0/hackmd-mcp).
56 
57## Configuration
58### Environment Variables (STDIO Transport and HTTP Transport server where host provides the config)
59 
60When using the STDIO transport or hosting the HTTP transport server, you can pass configuration via environment variables:
61- `HACKMD_API_TOKEN`: HackMD API Token (Required for all operations)
62- `HACKMD_API_URL`: (Optional) HackMD API URL (Defaults to https://api.hackmd.io/v1)
63 
64Environment variables applied only for the HTTP transport server:
65- `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.
66 
67> [!CAUTION]
68> 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.
69 
70### HTTP Headers (HTTP Transport where user provides the config)
71 
72When using the HTTP transport, user can pass configuration via HTTP headers:
73- `Hackmd-Api-Token`: HackMD API Token (Required for all operations)
74- `Hackmd-Api-Url`: (Optional) HackMD API URL (Defaults to https://api.hackmd.io/v1)
75 
76If the user provides the token in the header, while the server also has `HACKMD_API_TOKEN` set, the header value will take precedence.
77 
78### Get a HackMD API Token
79 
80To get an API token, follow these steps:
81 
821. Go to [HackMD settings](https://hackmd.io/settings#api).
832. Click on "Create API Token".
843. Copy the generated token and use it in your `.env` file or environment variables.
85 
86## Available Tools
87 
88### Profile Tools
89- **get_user_info**: Get information about the authenticated user
90 
91### Teams Tools
92- **list_teams**: List all teams accessible to the user
93 
94### History Tools
95- **get_history**: Get user's reading history
96 
97### Team Notes Tools
98- **list_team_notes**: List all notes in a team
99- **create_team_note**: Create a new note in a team
100- **update_team_note**: Update an existing note in a team
101- **delete_team_note**: Delete a note in a team
102 
103### User Notes Tools
104- **list_user_notes**: List all notes owned by the user
105- **get_note**: Get a note by its ID
106- **create_note**: Create a new note
107- **update_note**: Update an existing note
108- **delete_note**: Delete a note
109 
110## Example Usage
111 
112### Basic Note Management
113 
114```
115Can you help me manage my HackMD notes?
116```
117 
118### List Notes
119 
120```
121Please list all my notes.
122```
123 
124### Create a New Note
125 
126````
127Create a new note with the title "Meeting Notes" and content:
128```
129# Meeting Notes
130 
131Discussion points:
132- Item 1
133- Item 2
134```
135````
136 
137### Team Collaboration
138 
139```
140Show me all the teams I'm part of and list the notes in the first team.
141```
142 
143## Local Development
144 
145This project uses [pnpm](https://pnpm.io) as its package manager.
146 
147Clone the repository and install dependencies:
148 
149```bash
150git clone https://github.com/yuna0x0/hackmd-mcp.git
151cd hackmd-mcp
152pnpm install
153```
154 
155### Configuration
156 
1571. Create a `.env` file by copying the example:
158```bash
159cp env.example .env
160```
161 
1622. Edit the `.env` file and add your HackMD API token:
163```
164HACKMD_API_TOKEN=your_api_token
165```
166 
167## Debugging with MCP Inspector
168 
169You can use the MCP Inspector to test and debug the HackMD MCP server:
170 
171```bash
172npx @modelcontextprotocol/inspector -e HACKMD_API_TOKEN=your_api_token npx hackmd-mcp
173 
174# Use this instead when Local Development
175pnpm run inspector
176```
177 
178Then open your browser to the provided URL (usually http://localhost:6274) to access the MCP Inspector interface. From there, you can:
179 
1801. Connect to your running HackMD MCP server
1812. Browse available tools
1823. Run tools with custom parameters
1834. View the responses
184 
185This is particularly useful for testing your setup before connecting it to MCP clients like Claude Desktop.
186 
187## Docker
188 
189Pull from GitHub Container Registry:
190```bash
191docker pull ghcr.io/yuna0x0/hackmd-mcp
192```
193 
194Docker build (Local Development):
195```bash
196docker build -t ghcr.io/yuna0x0/hackmd-mcp .
197```
198 
199Docker multi-platform build (Local Development):
200```bash
201docker buildx build --platform linux/amd64,linux/arm64 -t ghcr.io/yuna0x0/hackmd-mcp .
202```
203 
204## MCP Bundles (MCPB)
205 
206To create an MCP Bundle for this server, run:
207```bash
208pnpm run pack:mcpb
209```
210 
211## Security Notice
212 
213This MCP server accepts your HackMD API token in the .env file, environment variable or HTTP header. Keep this information secure and never commit it to version control.
214 
215## License
216 
217This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
218