📝 Joplin MCP 服务器

这是一个针对 Joplin 的模型上下文协议（MCP）服务器，它通过 模型上下文协议 实现笔记访问。非常适合与像 Claude 这样的AI助手进行集成。

✨ 特性

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

🚀 安装

先决条件

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

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

# 创建并激活虚拟环境
uv venv
source .venv/bin/activate  # 在 Windows 上使用：.venv\Scripts\activate

# 安装依赖项
```bash
uv pip install -e .

⚙️ 配置

Joplin API Token

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

在项目目录中创建一个 .env 文件：

JOPLIN_TOKEN=your_api_token_here

Claude 桌面版设置

1. 安装 Claude 桌面版

   • 下载 Claude 桌面版
   • 确保您拥有最新版本（菜单：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_m_ 替换为您的项目的绝对路径

   重要：Claude 桌面版需要完整的 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 (布尔值，可选)：如果为真，则永久删除笔记

import_markdown

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

参数：

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

🧪 开发

调试模式

要以调试模式启动服务器：

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

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

📄 许可证

MIT 许可证 - 版权所有 (c) 2025 David Weigend

👤 作者

David Weigend

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

🤝 贡献

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