note-mcp-server

以 Model Context Protocol（stdio）連接 Notes API v2，讓 Cursor 等客戶端透過工具列出／讀寫筆記、上傳圖片、發送 Web Push。

需求

• Node.js 18+
• 已註冊之 Notes API（路徑形如：{網站}/api/notes/{socialite}/{加密 token}）

安裝

cd /path/to/note-mcp-server
npm install

設定 .env

在 index.js 同一目錄建立 .env（本專案已將 .env 列入 .gitignore，請勿提交私密內容）。

方式 A：拆開設定（建議）

與 Laravel 端 Socialite 提供者代號 及 加密後的路徑 token 對齊，由程式組出完整 API base：

| 變數 | 說明 | |------|------| | notes_url 或 NOTES_URL | 站台根網址，例如 https://notes.example.com（不要結尾斜線） | | socialite 或 SOCIALITE | 路徑中的提供者代號，例如 github（依你後端路由為準） | | key 或 KEY | 路徑最後一段的 加密 token | | socialite_id 或 SOCIALITE_ID | 與 key 擇一即可；語意相同，都是該段加密字串 |

實際請求的 base 為：

{notes_url}/api/notes/{socialite}/{key 或 socialite_id}

範例：

notes_url=https://notes.example.com
socialite=github
key=eyJpdiI6I…（你的加密 token，整段貼上）

若你習慣用「加密 socialite id」命名，可改為：

notes_url=https://notes.example.com
socialite=github
socialite_id=eyJpdiI6I…

方式 B：整段 API base（選用）

若已持有完整 API URL（到 token 為止、無結尾斜線），可只設：

| 變數 | 說明 | |------|------| | NOTES_API_BASE | 例如 https://notes.example.com/api/notes/github/eyJ… |

優先序： 只要設了 NOTES_API_BASE，就會 忽略 方式 A 的 notes_url / socialite / key。

參考檔案

• .env.example：不含密鑰的範本，可複製為 .env 再填入。
• 啟動時會執行 dotenv，從 index.js 所在目錄 讀取 .env，與終端機目前工作目錄無關（方便 Cursor 從任意 cwd 啟動 MCP）。

在 Cursor 中掛載

於 使用者 或 專案 的 .cursor/mcp.json 加入（路徑請改成你的本機路徑）：

{
  "mcpServers": {
    "note-assistant": {
      "command": "node",
      "args": ["/path/to/note-mcp-server/index.js"],
      "env": {}
    }
  }
}

• 不必在 mcp.json 重複貼 token**：放在 note-mcp-server 目錄下的 .env 即可。
• 若仍想由 Cursor 注入環境變數，可在 env 內設定 NOTES_API_BASE 或 notes_url / socialite / key（會覆寫／補齊系統環境；.env 仍會載入，順序依 dotenv 與既有 process.env 行為）。

儲存後在 Settings → Tools & MCPs 確認 note-assistant 為啟用狀態；必要時 Reload Window。

提示： 在 Agent 對話裡，內部工具伺服器名稱可能顯示為 user-note-assistant（user- 前綴），與設定裡的顯示名稱不同屬正常現象。

提供的 MCP 工具

| 工具 | 說明 | |------|------| | list_notes | GET 列表，支援 search / tag / page / limit（預設 10），每筆附 note_url | | read_note | GET 單筆，支援 c_id 或 last，回傳附 note_url | | create_note | POST 新增，content 必填，title 可選 | | update_note | POST 修改，c_id 必填，支援 content、title、append、prepend | | delete_note | POST 刪除，c_id + action=delete | | tag | GET 搜尋，根據標籤名稱找出筆記內容 | | upload_image | multipart，image_base64、可選 filename | | send_push | POST 推播，message 必填，title / url 可選 |

完整 REST 行為請對你的 API 網址加上 /help 查官方說明。

前台筆記網址格式：

{notes_url}/app/notes/content/{c_id}

Agent 安全流程（重要）

• 只要使用者貼出或提到敏感設定（例如 key、token、NOTES_API_BASE、socialite_id），完成設定或操作後，代理必須主動執行：

echo -n "" | pbcopy

• 回覆中必須明確告知「剪貼簿已清空」。
• 此流程屬於預設安全規範，不需等待使用者額外提醒。

常見問題

啟動失敗、訊息請建立 .env

代表未滿足任一組條件：請設 NOTES_API_BASE，或同時設 notes_url + socialite +（key 或 socialite_id）。

不要用終端機手動當 MCP 用

MCP 須由 Cursor 子程序 以 stdio 啟動；在終端機長駐執行 node index.js 不會自動掛進 Cursor。

手動除錯（可選）

僅供本機檢查流程，不是正式掛載 MCP：

node /path/to/note-mcp-server/index.js

程序會卡在 stdio 等待，除錯完請 Ctrl+C 結束。

授權

ISC（見 package.json）。