讓 Claude Code 可以直接操作你的 HackMD 筆記 — 建立、讀取、更新、刪除，通通不用離開 Claude。
這是一個 MCP 伺服器（其實就是你電腦上的小程式），它讓 Claude 可以透過 HackMD 的官方 API 幫你管理筆記。
能做什麼？
- 列出你所有筆記
- 讀取筆記內容
- 建立新筆記（發表到你的 HackMD）
- 更新筆記內容或權限
- 刪除筆記
- 操作團隊筆記
- 查詢你的個人資料、瀏覽歷史
- 登入 HackMD
- 右上角頭像 → Settings → API
- 點 Create API token
- 取個名字（例如
claude-code-mcp） - 複製 token（關掉視窗就看不到第二次了，要妥善保存）
⚠️ 這個 token 擁有你帳號筆記的完整讀寫刪權限，等同密碼：不要提交進 git、不要貼進跟別人共用的專案.mcp.json、不要貼在截圖裡。
方式 A：用 uvx（推薦，零安裝）
不用 pip install，直接在設定檔用 uvx 讓它自動下載執行。
前提：你要有 uv 工具：
# 安裝 uv（如果還沒裝）
# Windows PowerShell:
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# macOS / Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh方式 B：從 GitHub 安裝
pip install git+https://github.com/unbias38/hackmd-mcp.git方式 C：clone 下來自己裝（方便改程式碼）
git clone https://github.com/unbias38/hackmd-mcp.git
cd hackmd-mcp
pip install -e .推薦做法：一行 CLI 搞定（--scope user = 你所有專案都能用）：
claude mcp add --scope user --env HACKMD_TOKEN=你的token hackmd -- uvx --from git+https://github.com/unbias38/hackmd-mcp.git hackmd-mcp進階：不想把 token 明文寫進設定檔？ 先把 token 設成作業系統的環境變數（Windows：系統內容 → 環境變數；macOS/Linux：shell profile），設定檔用展開語法引用：
claude mcp add --scope user --env "HACKMD_TOKEN=\${HACKMD_TOKEN}" hackmd -- uvx --from git+https://github.com/unbias38/hackmd-mcp.git hackmd-mcp手動編輯設定檔（fallback）
編輯 ~/.claude.json（Windows：C:\Users\你的使用者名稱\.claude.json），在 mcpServers 區段加入：
如果用 uvx（方式 A）：
{
"mcpServers": {
"hackmd": {
"command": "uvx",
"args": ["--from", "git+https://github.com/unbias38/hackmd-mcp.git", "hackmd-mcp"],
"env": {
"HACKMD_TOKEN": "${HACKMD_TOKEN}"
}
}
}
}如果用 pip 安裝（方式 B / C）：
{
"mcpServers": {
"hackmd": {
"command": "python",
"args": ["-m", "hackmd_mcp.server"],
"env": {
"HACKMD_TOKEN": "${HACKMD_TOKEN}"
}
}
}
}env 值支援 ${VAR} 環境變數展開；不想用環境變數就直接貼 token（記得這個檔案別分享）。如果 .claude.json 已經有其他 MCP，不要蓋掉，只要在 mcpServers 物件裡新增 "hackmd": {...} 這一塊就好。
關掉再重開。打開後問 Claude：
「幫我列出 HackMD 上所有的筆記」
成功的話，Claude 就會用這個 MCP 呼叫 HackMD API，把你的筆記清單抓回來。
| 工具 | 用途 |
|---|---|
hackmd_get_me |
查詢自己的 profile |
hackmd_get_history |
瀏覽歷史記錄（分頁） |
hackmd_list_notes |
列出筆記（分頁、精簡欄位，不含內文） |
hackmd_get_note |
讀某篇筆記（含完整內文） |
hackmd_create_note |
建立新筆記（含 tags/description/permalink） |
hackmd_update_note |
更新內容、標題、tags、描述或權限 |
hackmd_delete_note |
刪除筆記（進垃圾桶，可救回） |
hackmd_list_trash |
列出垃圾桶裡的筆記 |
hackmd_restore_note |
從垃圾桶救回筆記 |
hackmd_list_teams |
列出我的團隊 |
hackmd_list_team_notes |
列出團隊筆記（分頁） |
hackmd_get_team_note |
讀團隊筆記 |
hackmd_create_team_note |
建立團隊筆記 |
hackmd_update_team_note |
更新團隊筆記 |
hackmd_delete_team_note |
刪除團隊筆記 |
列表工具都有分頁：limit（預設 20，最大 100）+ offset，回傳裡的 has_more / next_offset 告訴你還有沒有下一頁。列表只回 9 個關鍵欄位、不含筆記內文——要內文請用 hackmd_get_note。
標題的優先序（HackMD 官方規則）：content 裡的 YAML title: > content 開頭的 # H1 > title 參數。也就是說 content 有 H1 時，title 參數會被蓋掉。
配合 hackmd-note Skill 一起用最爽：
你： 幫我把這份會議記錄改成 HackMD 格式，然後上傳到我的 HackMD
Claude：
- 啟動
hackmd-noteskill → 套用 HackMD 語法（色塊、spoiler 等）- 呼叫
create_note→ 把成品推上 HackMD- 回傳筆記連結給你
HackMD 筆記有三種權限，參數值如下：
| 值 | 意義 |
|---|---|
owner |
只有你能讀/寫 |
signed_in |
所有 HackMD 登入使用者能讀/寫 |
guest |
完全公開 |
建立筆記時 read_permission 跟 write_permission 可以分別設定，例如：
read_permission="guest" # 任何人都能讀
write_permission="owner" # 只有你能改
留言權限 comment_permission（只能在建立時設定，API 不支援事後修改）：
| 值 | 意義 |
|---|---|
disabled |
關閉留言功能 |
forbidden |
顯示但禁止留言 |
owners |
只有擁有者能留言 |
signed_in_users |
登入使用者能留言 |
everyone |
所有人能留言 |
不指定時採用你 HackMD 帳號的預設值。
HackMD API 的官方限制：
- 短期：每 5 分鐘 100 次請求
- 免費方案：每月 2,000 次
- Prime 方案：每月 20,000 次
正常使用不會碰到上限，但如果你要大批次備份、匯入很多筆記，可能要留意。
- 確認
.claude.json的 JSON 格式有沒有壞掉（逗號、引號） - 確認 Claude Code 有完全關掉再重開
- 檢查 Claude Code 啟動時的訊息，看有沒有 MCP 啟動失敗的錯誤
Token 沒設對。確認：
.claude.json裡的HACKMD_TOKEN是不是正確複製- Token 前後有沒有多餘的空白
- Token 沒有被撤銷
撞到速率限制了，等 5 分鐘再試。
用 pip install 方式的話，確認你是在 Claude 會用到的那個 Python 環境安裝的。如果用 conda / venv，command 可能要改成完整路徑，例如：
"command": "C:/path/to/venv/Scripts/python.exe"MIT