hackmd-mcp

讓 Claude Code 可以直接操作你的 HackMD 筆記 — 建立、讀取、更新、刪除，通通不用離開 Claude。

這是什麼？

這是一個 MCP 伺服器（其實就是你電腦上的小程式），它讓 Claude 可以透過 HackMD 的官方 API 幫你管理筆記。

能做什麼？

• 列出你所有筆記
• 讀取筆記內容
• 建立新筆記（發表到你的 HackMD）
• 更新筆記內容或權限
• 刪除筆記
• 操作團隊筆記
• 查詢你的個人資料、瀏覽歷史

---

安裝步驟（3 步驟）

第 1 步：取得 HackMD API Token

1. 登入 HackMD
2. 右上角頭像 → Settings → API
3. 點 Create API token
4. 取個名字（例如 claude-code-mcp）
5. 複製 token（關掉視窗就看不到第二次了，要妥善保存）

第 2 步：安裝這個 MCP

方式 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 .

第 3 步：設定 Claude Code

編輯你的 Claude 設定檔：

• Windows： C:\Users\你的使用者名稱\.claude.json
• macOS / Linux： ~/.claude.json

在 mcpServers 區段加入：

如果用 uvx（方式 A）：

{
  "mcpServers": {
    "hackmd": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/unbias38/hackmd-mcp.git", "hackmd-mcp"],
      "env": {
        "HACKMD_TOKEN": "你的token貼這裡"
      }
    }
  }
}

如果用 pip 安裝（方式 B / C）：

{
  "mcpServers": {
    "hackmd": {
      "command": "python",
      "args": ["-m", "hackmd_mcp.server"],
      "env": {
        "HACKMD_TOKEN": "你的token貼這裡"
      }
    }
  }
}

重要： 如果 .claude.json 已經有其他 MCP，不要蓋掉，只要在 mcpServers 物件裡新增 "hackmd": {...} 這一塊就好。

第 4 步：重啟 Claude Code

關掉再重開。打開後問 Claude：

「幫我列出 HackMD 上所有的筆記」

成功的話，Claude 就會用這個 MCP 呼叫 HackMD API，把你的筆記清單抓回來。

---

可用工具清單

工具	用途
get_me	查詢自己的 profile
get_history	瀏覽歷史記錄
list_notes	列出所有筆記
get_note	讀某篇筆記
create_note	建立新筆記
update_note	更新筆記內容或權限
delete_note	刪除筆記
list_teams	列出我的團隊
list_team_notes	列出團隊筆記
get_team_note	讀團隊筆記
create_team_note	建立團隊筆記
update_team_note	更新團隊筆記
delete_team_note	刪除團隊筆記

---

使用範例

配合 hackmd-note Skill 一起用最爽：

你： 幫我把這份會議記錄改成 HackMD 格式，然後上傳到我的 HackMD

Claude：

1. 啟動 hackmd-note skill → 套用 HackMD 語法（色塊、spoiler 等）
2. 呼叫 create_note → 把成品推上 HackMD
3. 回傳筆記連結給你

---

權限說明

HackMD 筆記有三種權限，參數值如下：

值	意義
owner	只有你能讀/寫
signed_in	所有 HackMD 登入使用者能讀/寫
guest	完全公開

建立筆記時 read_permission 跟 write_permission 可以分別設定，例如：

read_permission="guest"      # 任何人都能讀
write_permission="owner"     # 只有你能改

---

速率限制

HackMD API 的官方限制：

• 短期：每 5 分鐘 100 次請求
• 免費方案：每月 2,000 次
• Prime 方案：每月 20,000 次

正常使用不會碰到上限，但如果你要大批次備份、匯入很多筆記，可能要留意。

---

疑難排解

Claude 說找不到 hackmd 相關工具

• 確認 .claude.json 的 JSON 格式有沒有壞掉（逗號、引號）
• 確認 Claude Code 有完全關掉再重開
• 檢查 Claude Code 啟動時的訊息，看有沒有 MCP 啟動失敗的錯誤

回傳 Error 401

Token 沒設對。確認：

• .claude.json 裡的 HACKMD_TOKEN 是不是正確複製
• Token 前後有沒有多餘的空白
• Token 沒有被撤銷

回傳 Error 429

撞到速率限制了，等 5 分鐘再試。

Python 找不到 hackmd_mcp 模組

用 pip install 方式的話，確認你是在 Claude 會用到的那個 Python 環境安裝的。如果用 conda / venv，command 可能要改成完整路徑，例如：

"command": "C:/path/to/venv/Scripts/python.exe"

---

授權

MIT

相關連結

• HackMD API 文件
• HackMD Developer Portal
• MCP 協定
• hackmd-note Skill（姊妹專案）