📝 Joplin MCP 服务器

一个用于 Joplin 的 Model Context Protocol (MCP) 服务器，通过 Model Context Protocol 实现笔记访问。非常适合与 Claude 等 AI 助手集成。

✨ 特性

• 🔍 搜索笔记: 全文搜索所有笔记
• 📖 阅读笔记: 检索单个笔记
• ✏️ 编辑笔记: 创建新笔记并更新现有笔记
• 🗑️ 删除笔记: 将笔记移至回收站或永久删除
• 📥 Markdown 导入: 作为笔记导入 Markdown 文件
• 🤖 AI 集成: 无缝集成 Claude 和其他支持 MCP 的 AI 助手

🚀 安装

前提条件

• Python 3.10 或更高版本
• 启用了 Web Clipper 服务的 Joplin Desktop
• uv（Python 包管理器）

bash

克隆仓库

git clone https://github.com/dweigend/joplin-mcp.git
cd joplin-mcp

创建并激活虚拟环境

uv venv
source .venv/bin/activate # 在 Windows 上: .venvScriptsactivate

安装依赖项

bash
uv pip install -e .

⚙️ 配置

Joplin API Token

1. 打开 Joplin Desktop
2. 转到 工具 -> 选项 -> Web Clipper
3. 启用 Web Clipper 服务
4. 复制 API Token

在项目目录中创建一个 .env 文件：
bash
JOPLIN_TOKEN=your_api_token_here

Claude Desktop 设置

1. 安装 Claude Desktop

   • 下载 Claude Desktop
   • 确保你拥有最新版本（菜单：Claude -> 检查更新...）

2. 配置 MCP 服务器
   json
   {
   "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:UsersusernameAppDataLocalMicrosoftWindowsAppsuv.exe
   • 将 /PATH/TO/YOUR/PROJECT/joplin_mcp 替换为你的项目的绝对路径

   重要提示：Claude Desktop 需要 uv 的完整路径，因为它无法访问 shell 环境变量。

🛠️ 可用工具

search_notes

在 Joplin 中搜索笔记。

参数:

• query (字符串): 搜索查询
• limit (整数, 可选): 最大结果数量 (默认: 100)

get_note

通过 ID 检索特定笔记。

参数:

• note_id (字符串): 笔记 ID

create_note

创建新笔记。

参数:

• title (字符串): 笔记标题
• body (字符串, 可选): 笔记内容（Markdown 格式）
• parent_id (字符串, 可选): 父文件夹 ID
• is_todo (布尔值, 可选): 是否为待办事项

update_note

更新现有笔记。

参数:

• note_id (字符串): 要更新的笔记 ID
• title (字符串, 可选): 新标题
• body (字符串, 可选): 新内容
• parent_id (字符串, 可选): 新父文件夹 ID
• is_todo (布尔值, 可选): 新待办事项状态

delete_note

删除笔记。

参数:

• note_id (字符串): 要删除的笔记 ID
• permanent (布尔值, 可选): 如果为 true，则永久删除笔记

import_markdown

将 Markdown 文件作为新笔记导入。

参数:

• file_path (字符串): Markdown 文件的路径

🧪 开发

调试模式

以调试模式启动服务器：

bash
MCP_LOG_LEVEL=debug mcp dev src/mcp/joplin_mcp.py

这将在 http://localhost:5173 启动 MCP Inspector，您可以在其中测试工具。

📄 许可证

MIT 许可证 - 版权所有 © 2025 David Weigend

👤 作者

David Weigend

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

🤝 贡献

欢迎贡献、问题和功能请求！
访问 问题页面。