Noteplan MCP

🚀 NotePlan MCP Server

NotePlan MCP Server 是一個消息控制協議（MCP）服務器，它讓 Claude Desktop 能夠與 NotePlan.co 進行交互。該服務器實現了 Claude 與 NotePlan 筆記的無縫集成，允許你在 Claude 對話中直接查詢、搜索、創建和更新筆記。

🚀 快速開始

1. 安裝依賴：

   npm install
   

2. 構建項目：

   npm run build
   

3. 測試服務器：

   npm start
   

   你應該會看到："NotePlan MCP server running on stdio"

4. 配置 Claude Desktop（詳見下面的詳細設置）

✨ 主要特性

• 讀取筆記：獲取所有筆記、通過 ID 獲取特定筆記，或獲取特定文件夾中的筆記
• 搜索：對所有筆記進行全文搜索
• 創建筆記：創建帶有標題、內容和文件夾組織的新筆記
• 每日筆記：創建和管理具有自動日期格式的每日筆記
• 更新筆記：修改現有筆記的標題和內容
• 文件夾組織：按文件夾組織和過濾筆記

📦 安裝指南

選項 1：從 GitHub 克隆

git clone https://github.com/bscott/noteplan-mcp.git
cd noteplan-mcp
npm install

選項 2：作為 NPM 包安裝（即將推出）

npm install -g noteplan-mcp

📚 詳細文檔

Claude Desktop 配置

要在 Claude Desktop 中使用此 MCP 服務器，請在你的 Claude Desktop 配置文件中添加以下配置：

步驟 1：定位配置文件

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

步驟 2：添加 NotePlan MCP 服務器

在 claude_desktop_config.json 中添加以下配置：

{
  "mcpServers": {
    "noteplan": {
      "command": "node",
      "args": ["/absolute/path/to/noteplan-mcp/build/index.js"],
      "cwd": "/absolute/path/to/noteplan-mcp"
    }
  }
}

重要提示：將 /absolute/path/to/noteplan-mcp 替換為你克隆此倉庫的實際路徑。

步驟 3：重啟 Claude Desktop

保存配置後，完全重啟 Claude Desktop 以使更改生效。

可用工具

配置完成後，你可以在 Claude 對話中使用以下工具：

在 Claude 中的使用示例

設置完成後，你可以向 Claude 提出以下請求：

• "Show me all my notes"（顯示我所有的筆記）
• "Search for notes containing 'project planning'"（搜索包含 'project planning' 的筆記）
• "Create a new note titled 'Meeting Notes' in the 'Work' folder"（在 'Work' 文件夾中創建一個名為 'Meeting Notes' 的新筆記）
• "Get today's daily note"（獲取今天的每日筆記）
• "Update note ID 'note123' with new content"（用新內容更新 ID 為 'note123' 的筆記）

Claude 將自動使用相應的 NotePlan MCP 工具來滿足這些請求。

開發

開發模式

npm run dev

此命令將構建 TypeScript 代碼，並使用 nodemon 在文件更改時自動重啟服務器。

構建

npm run build

將 TypeScript 代碼編譯為 JavaScript 並輸出到 build/ 目錄。

測試

npm test

代碼檢查

npm run lint

項目結構

noteplan-mcp/
├── src/
│   ├── index.ts               # 主 MCP 服務器實現
│   ├── index.js               # HTTP 服務器（可選）
│   └── services/
│       └── noteService.ts     # 筆記管理邏輯
├── build/                     # 編譯後的 JavaScript 輸出
│   ├── index.js               # 編譯後的 MCP 服務器
│   └── services/
│       └── noteService.js     # 編譯後的筆記服務
├── tests/
│   └── index.test.js          # 測試文件
├── tsconfig.json              # TypeScript 配置
├── package.json
└── README.md

故障排除

Claude Desktop 無法連接

1. 檢查文件路徑：確保 claude_desktop_config.json 中的路徑是絕對路徑且正確。
2. 檢查 Node.js：確保 Node.js 已安裝並可從你的 PATH 訪問。
3. 檢查日誌：查看 Claude Desktop 日誌中的錯誤消息：
   • macOS：~/Library/Logs/Claude/mcp-server-noteplan.log
   • Windows：%LOCALAPPDATA%\Claude\Logs\mcp-server-noteplan.log

常見錯誤消息

• "Cannot find module '/src/mcp-server.js'"：配置中的路徑不正確，請使用絕對路徑，而不是相對路徑。
• "Server disconnected"：檢查 Node.js 是否已安裝，並且服務器可以通過 npm start 啟動。

測試你的設置

1. 手動測試服務器：

   cd /path/to/noteplan-mcp
   npm run build
   npm start
   

2. 使用 MCP 檢查器進行調試：

   npm run inspector
   

3. 檢查 Claude Desktop 日誌中的連接狀態。

4. 在 Claude 中嘗試一個簡單的命令："Can you show me my notes?"（你能顯示我的筆記嗎？）

配置

自定義 NotePlan 目錄

默認情況下，服務器會在標準位置查找 NotePlan 文件。如果你使用自定義目錄，可以修改 noteService.js 文件以指向你的 NotePlan 數據目錄。

環境變量

目前不需要環境變量，但未來版本可能支持：

• NOTEPLAN_DATA_DIR：自定義 NotePlan 數據目錄
• MCP_LOG_LEVEL：日誌詳細程度

貢獻

1. 分叉倉庫
2. 創建功能分支：git checkout -b my-new-feature
3. 進行更改並添加測試
4. 運行測試套件：npm test
5. 運行代碼檢查：npm run lint
6. 提交更改：git commit -am 'Add some feature'
7. 推送到分支：git push origin my-new-feature
8. 提交拉取請求

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE 文件。

支持

• 若遇到 bug 或有功能請求，請在 GitHub 上創建一個 issue。
• 對於一般的 MCP 問題，請查看 MCP 文檔。
• 對於設置問題，請查看 Claude Desktop 文檔。