Joplin

🚀 📝 Joplin MCP 服務器

Joplin MCP 服務器是為 Joplin 實現的 Model Context Protocol (MCP) 服務器，藉助該協議可實現筆記訪問，特別適合與 Claude 等 AI 助手集成，為筆記管理與 AI 交互提供了便利。

🚀 快速開始

Joplin MCP 服務器能讓你通過 MCP 協議訪問 Joplin 筆記，還可與 AI 助手集成。以下是使用前的安裝和配置步驟。

✨ 主要特性

• 🔍 搜索筆記：可在所有筆記中開展全文搜索。
• 📖 閱讀筆記：能檢索單個筆記。
• ✏️ 編輯筆記：支持創建新筆記並更新現有筆記。
• 🗑️ 刪除筆記：可將筆記移至回收站或永久刪除。
• 📥 Markdown 導入：能把 Markdown 文件導入為筆記。
• 🤖 AI 集成：可與 Claude 及其他支持 MCP 的 AI 助手實現無縫集成。

📦 安裝指南

先決條件

• Python 3.10 或更高版本。
• 已啟用 Web Clipper 服務的 Joplin Desktop。
• uv（Python 包管理器）。

# 克隆倉庫
git clone https://github.com/dweigend/joplin-mcp.git
cd joplin-mcp

# 創建並激活虛擬環境
uv venv
source .venv/bin/activate  # 在 Windows 中：.venv\Scripts\activate

# 安裝依賴項
uv pip install -e .

⚙️ 配置

Joplin API 令牌

1. 打開 Joplin Desktop。
2. 轉到工具 -> 選項 -> Web Clipper。
3. 啟用 Web Clipper 服務。
4. 複製 API 令牌。

在項目目錄中創建一個 .env 文件：

JOPLIN_TOKEN=your_api_token_here

Claude Desktop 設置

1. 安裝 Claude Desktop

   • 下載 Claude Desktop。
   • 確保使用最新版本（菜單：Claude -> 檢查更新...）。

2. 配置 MCP 服務器

   {
     "mcpServers": {
       "joplin": {
         "command": "/PATH/TO/UV/uv",
         "args": [
           "--directory",
           "/PATH/TO/YOUR/PROJECT/joplin_mcp",
           "run",
           "src/mcp/joplin_mcp.py"
         ]
       }
     }
   }
   

   • 替換 /PATH/TO/UV/uv 為 uv 安裝的絕對路徑。
     • 使用 which uv 找到路徑（例如 macOS: /Users/username/.local/bin/uv）。
     • 示例 Windows: C:\Users\username\AppData\Local\Microsoft\WindowsApps\uv.exe。
   • 替換 /PATH/TO/YOUR/PROJECT/joplin_mcp 為項目絕對路徑。

   ⚠️ 重要提示

   Claude Desktop 需要完整的 uv 路徑，因為它無法訪問 shell 環境變量。

💻 使用示例

基礎用法

本服務器提供了搜索、閱讀、編輯、刪除筆記，導入 Markdown 文件以及與 AI 助手集成等功能。以下是部分功能的使用示例：

搜索筆記

# 搜索包含特定關鍵詞的筆記
# 這裡假設你已經配置好環境並啟動了服務器
# 具體的搜索命令需要根據服務器的接口來實現
# 示例代碼僅為示意
search_command "keyword"

閱讀筆記

# 閱讀指定 ID 的筆記
# 同樣，具體命令根據接口實現
read_command note_id

高級用法

與 AI 助手集成

# 假設你已經配置好 Claude Desktop 與 MCP 服務器
# 可以在 Claude 中使用服務器提供的筆記信息
# 這裡展示如何在 Claude 中調用服務器功能
# 示例代碼僅為示意
claude_command "get_note_info"

📚 詳細文檔

可用工具

• 搜索筆記：在所有筆記中進行全文搜索。
• 閱讀筆記：檢索單個筆記。
• 編輯筆記：創建新筆記或更新現有筆記。
• 刪除筆記：將筆記移動到回收站或永久刪除。
• Markdown 導入：導入 Markdown 文件作為筆記。
• AI 集成：與 Claude 和其他支持 MCP 的 AI 助手無縫集成。

開發

調試模式

要啟用調試模式，請在配置中設置：

DEBUG=True

日誌記錄

默認日誌級別為 INFO。要更改日誌級別，請設置：

LOG_LEVEL=DEBUG  # 可選值：DEBUG, INFO, WARNING, ERROR, CRITICAL

📄 許可證

本項目遵循 MIT License。

🎤 作者

David Weigend

• 網站: weigend.studio
• GitHub: @dweigend

🤝 貢獻

歡迎貢獻、問題和功能請求！訪問 問題頁面。