MCP Joplin 服务器

一个与 Joplin 笔记集成的模型上下文协议 (MCP) 服务器，允许 AI 客户端（如 Perplexity）通过 Joplin 的 Web Clipper API 访问和操作您的笔记本和笔记。

功能特性

🔍 搜索功能：搜索笔记和笔记本
📖 内容读取：获取特定笔记的完整内容
📝 创建功能：创建新的笔记和笔记本
✏️ 更新/编辑功能：更新笔记内容、追加内容到笔记以及重命名笔记本
🗑️ 删除功能：删除笔记和笔记本（支持移至回收站或永久删除）
🔄 移动功能：将笔记移动到不同的笔记本
📋 列表功能：列出所有笔记本以及特定笔记本内的笔记

要求

Joplin 桌面版 - 确保已安装并运行
Node.js 18+ - 运行 MCP 服务器所必需
启用 Web Clipper - 在 Joplin 中启用 Web Clipper 服务

安装与设置

1. 启用 Joplin Web Clipper

打开 Joplin 桌面应用程序
进入 工具 → 选项 → Web Clipper
勾选 启用 Web Clipper 服务
记下显示的 端口号（通常为 41184）
复制 API 令牌（如果需要身份验证）

2. 安装 MCP Joplin 服务器

# Clone or download this project
cd mcp-joplin

# Install dependencies
npm install

# Compile TypeScript
npm run build

3. 测试执行

# Run directly (will auto-detect Joplin service)
npm start

# Or specify port
npm start -- --port 41184

# Or specify token (if needed)
npm start -- --token YOUR_API_TOKEN

# View help
npm start -- --help

4. 使用 npx

# Global installation (recommended)
npm install -g .

# Then use anywhere
npx mcp-joplin

# Or run locally
npx . --port 41184

MCP 客户端配置

配置 Perplexity 或其他 MCP 客户端

将以下配置添加到您的 MCP 客户端配置文件中：

🔐 配置（需要 API 令牌）

此 MCP 服务器需要 Joplin API 令牌才能正常工作：

{
  "mcpServers": {
    "joplin": {
      "command": "npx",
      "args": [
        "/ABSOLUTE/PATH/TO/mcp-joplin",
        "--port",
        "41184",
        "--token",
        "YOUR_API_TOKEN"
      ]
    }
  }
}

💡 重要：此 MCP 服务器正常工作需要 API 令牌。

Claude Desktop 配置示例

Claude Desktop 配置

在 ~/Library/Application Support/Claude/claude_desktop_config.json 中：

{
  "mcpServers": {
    "joplin": {
      "command": "npx",
      "args": [
        "/Users/yourusername/path/to/mcp-joplin",
        "--token",
        "YOUR_API_TOKEN"
      ]
    }
  }
}

可用 MCP 工具

1. get_note_content

获取特定笔记的完整内容

Parameters: noteId (string) - The ID of the note

2. search_notes

搜索笔记

Parameters:
- query (string) - Search keywords
- limit (number, optional) - Result limit (default: 20)

3. search_notebooks

搜索笔记本

Parameters: query (string) - Search keywords

4. list_notebooks

列出所有笔记本

Parameters: None

5. list_notes

列出特定笔记本中的笔记

Parameters:
- notebookId (string) - The ID of the notebook
- limit (number, optional) - Result limit (default: 50)

5.1. list_sub_notebooks

列出特定笔记本内的子笔记本

Parameters:
- parentNotebookId (string) - The ID of the parent notebook

6. create_note

创建新笔记

Parameters:
- title (string) - Note title
- body (string) - Note content (Markdown format)
- notebookId (string, optional) - Target notebook ID

7. create_notebook

创建新笔记本

Parameters:
- title (string) - Notebook title
- parentId (string, optional) - Parent notebook ID (for sub-notebooks)

8. delete_note

删除笔记

Parameters:
- noteId (string) - ID of the note to delete
- permanent (boolean, optional) - Whether to permanently delete (default: false, moves to trash)

9. delete_notebook

删除笔记本

Parameters:
- notebookId (string) - ID of the notebook to delete
- permanent (boolean, optional) - Whether to permanently delete (default: false, moves to trash)

10. move_note

将笔记移动到不同的笔记本

Parameters:
- noteId (string) - ID of the note to move
- targetNotebookId (string) - Target notebook ID

11. update_note

更新现有笔记的标题和/或正文

Parameters:
- noteId (string) - ID of the note to update
- title (string, optional) - New note title
- body (string, optional) - New note content (full replacement, not a patch)

注意：

必须提供 title 或 body 中的至少一项
在替换笔记内容或重命名笔记时使用此工具

12. append_to_note

将内容追加到现有笔记的末尾

Parameters:
- noteId (string) - ID of the note to append to
- content (string) - Content to append
- separator (string, optional) - Separator inserted before appended content (default: "\n\n")

注意：

用于日志、会议记录、补充信息或测试结果
当意图是在不替换现有正文的情况下添加内容时，优先使用此工具而非 update_note

13. update_notebook

更新现有笔记本的标题

Parameters:
- notebookId (string) - ID of the notebook to update
- title (string) - New notebook title

14. scan_unchecked_items

扫描笔记本和子笔记本中未完成的待办事项 (- [ ])

Parameters:
- notebookId (string) - ID of the notebook to scan
- includeSubNotebooks (boolean, optional) - Whether to recursively scan sub-notebooks (default: true)

编辑语义

使用 update_note 替换笔记的标题和/或正文
使用 append_to_note 在保留现有内容的同时将内容添加到笔记末尾
使用 move_note 更改笔记所属的笔记本
使用 update_notebook 重命名笔记本

使用示例

AI 客户端中的对话示例：

You: "Search for notes containing 'Python'"
AI: Using search_notes tool to search for relevant notes...

You: "Create a new notebook called 'Learning Plan'"
AI: Using create_notebook tool to create a new notebook...

You: "Create a note about JavaScript in the Learning Plan notebook"
AI: Using list_notebooks to find the notebook ID, then using create_note to create the note...

You: "Show the complete content of a specific note"
AI: Using get_note_content tool to retrieve note content...

You: "Update the title of note abc123 to Weekly Review"
AI: Using update_note tool to rename the note...

You: "Append these test results to note abc123"
AI: Using append_to_note tool to add the new content to the end of the note...

You: "Rename notebook xyz789 to Project Archive"
AI: Using update_notebook tool to rename the notebook...

You: "Scan my project notebook for all uncompleted todo items"
AI: Using scan_unchecked_items tool to scan all sub-notebooks...

故障排除

连接问题

确认 Joplin 正在运行
- Joplin 桌面应用程序必须保持打开状态
检查 Web Clipper 设置
- 确保 Web Clipper 服务已启用
- 检查端口设置（默认 41184）

查看错误消息

# Use verbose mode to see errors
DEBUG=* npm start

常见错误

"Joplin Web Clipper service not found"：确保 Joplin 正在运行且 Web Clipper 已启用
"Connection refused"：检查端口设置是否正确
"Unauthorized" 或 "403 Forbidden"：需要 API 令牌（请参阅下方的说明）

🔑 需要 API 令牌

此 MCP 服务器正常工作需要 API 令牌。

获取 API 令牌

在 Joplin 中进入 工具 → 选项 → Web Clipper
复制显示的 令牌 (token)
在启动命令中添加 --token YOUR_TOKEN

开发

# Run in development mode
npm run dev

# Compile
npm run build

# Prepare for publishing
npm run prepublishOnly

技术架构

语言：TypeScript/Node.js
MCP SDK：@modelcontextprotocol/sdk
HTTP 客户端：axios
CLI：commander
API：Joplin Web Clipper API

技术细节

笔记本搜索：由于 Joplin 搜索 API 在文件夹搜索方面的限制，我们使用客户端过滤来实现笔记本搜索功能
分页处理：自动处理 Joplin API 的分页机制（默认每页 100 条），确保检索到完整的笔记本和笔记列表，解决了子笔记本显示不完整的问题
错误处理：完整的错误处理机制，包括 Joplin API 错误和网络连接错误
自动检测：支持自动检测 Joplin Web Clipper 端口 (41184-41194)

许可证

MIT 许可证

贡献

欢迎提交 Issue 和 Pull Request！

支持

如果您遇到问题，请：

检查 Joplin Web Clipper 是否正常运行
查看错误消息和日志
提交包含详细错误信息的 Issue