# hackmd-mcp

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

## 這是什麼？

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

**能做什麼？**

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

---

## 安裝步驟（3 步驟）

### 第 1 步：取得 HackMD API Token

1. 登入 [HackMD](https://hackmd.io)
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](https://github.com/astral-sh/uv) 工具：

```bash
# 安裝 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 安裝**

```bash
pip install git+https://github.com/unbias38/hackmd-mcp.git
```

**方式 C：clone 下來自己裝（方便改程式碼）**

```bash
git clone https://github.com/unbias38/hackmd-mcp.git
cd hackmd-mcp
pip install -e .
```

### 第 3 步：設定 Claude Code

**推薦做法：一行 CLI 搞定**（`--scope user` = 你所有專案都能用）：

```bash
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），設定檔用展開語法引用：

```bash
claude mcp add --scope user --env "HACKMD_TOKEN=\${HACKMD_TOKEN}" hackmd -- uvx --from git+https://github.com/unbias38/hackmd-mcp.git hackmd-mcp
```

<details>
<summary>手動編輯設定檔（fallback）</summary>

編輯 `~/.claude.json`（Windows：`C:\Users\你的使用者名稱\.claude.json`），在 `mcpServers` 區段加入：

**如果用 uvx（方式 A）：**

```json
{
  "mcpServers": {
    "hackmd": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/unbias38/hackmd-mcp.git", "hackmd-mcp"],
      "env": {
        "HACKMD_TOKEN": "${HACKMD_TOKEN}"
      }
    }
  }
}
```

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

```json
{
  "mcpServers": {
    "hackmd": {
      "command": "python",
      "args": ["-m", "hackmd_mcp.server"],
      "env": {
        "HACKMD_TOKEN": "${HACKMD_TOKEN}"
      }
    }
  }
}
```

`env` 值支援 `${VAR}` 環境變數展開；不想用環境變數就直接貼 token（記得這個檔案別分享）。如果 `.claude.json` 已經有其他 MCP，不要蓋掉，只要在 `mcpServers` 物件裡新增 `"hackmd": {...}` 這一塊就好。

</details>

### 第 4 步：重啟 Claude Code

關掉再重開。打開後問 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：**
> 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"     # 只有你能改
```

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

| 值 | 意義 |
|---|---|
| `disabled` | 關閉留言功能 |
| `forbidden` | 顯示但禁止留言 |
| `owners` | 只有擁有者能留言 |
| `signed_in_users` | 登入使用者能留言 |
| `everyone` | 所有人能留言 |

不指定時採用你 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` 可能要改成完整路徑，例如：

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

---

## 授權

MIT

## 相關連結

- [HackMD API 文件](https://api.hackmd.io/v1/docs)
- [HackMD Developer Portal](https://hackmd.io/@hackmd-api/developer-portal)
- [MCP 協定](https://modelcontextprotocol.io)
- [hackmd-note Skill（姊妹專案）](https://github.com/unbias38/my-claude-skills)