hackmd-mcp

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

這是什麼？

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

能做什麼？

• 列出你所有筆記

• 讀取筆記內容

• 建立新筆記（發表到你的 HackMD）

• 更新筆記內容或權限

• 刪除筆記

• 操作團隊筆記

• 查詢你的個人資料、瀏覽歷史

Related MCP server: Mowen Notes MCP Server

安裝步驟（3 步驟）

第 1 步：取得 HackMD API Token

1. 登入 HackMD

2. 右上角頭像 → Settings → API

3. 點 Create API token

4. 取個名字（例如 claude-code-mcp）

5. 複製 token（關掉視窗就看不到第二次了，要妥善保存）

⚠️ 這個 token 擁有你帳號筆記的完整讀寫刪權限，等同密碼：不要提交進 git、不要貼進跟別人共用的專案 .mcp.json、不要貼在截圖裡。

第 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

推薦做法：一行 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

編輯 ~/.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": {...} 這一塊就好。

第 4 步：重啟 Claude Code

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

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

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

可用工具清單

列表工具都有分頁：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：

1. 啟動 hackmd-note skill → 套用 HackMD 語法（色塊、spoiler 等）

2. 呼叫 create_note → 把成品推上 HackMD

3. 回傳筆記連結給你

權限說明

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

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

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

留言權限 comment_permission（只能在建立時設定，API 不支援事後修改）：

不指定時採用你 HackMD 帳號的預設值。

速率限制

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（姊妹專案）