📝 Joplin MCP 服务器

一个用于 Joplin 的模型上下文协议 (MCP) 服务器，它允许通过 模型上下文协议 访问笔记。非常适合与 Claude 等 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

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

⚙️ 配置

Joplin API Token

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

在项目目录中创建一个 .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 环境变量。

🛠️ 可用工具

search_notes

在 Joplin 中搜索笔记。

参数:

• query (string): 搜索查询
• limit (int, optional): 最大结果数 (默认: 100)

get_note

按 ID 检索特定笔记。

参数:

• note_id (string): 笔记的 ID

create_note

创建一个新笔记。

参数:

• title (string): 笔记标题
• body (string, optional): Markdown 格式的笔记内容
• parent_id (string, optional): 父文件夹的 ID
• is_todo (boolean, optional): 是否为待办事项

update_note

更新现有笔记。

参数:

• note_id (string): 要更新的笔记的 ID
• title (string, optional): 新标题
• body (string, optional): 新内容
• parent_id (string, optional): 新的父文件夹 ID
• is_todo (boolean, optional): 新的待办事项状态

delete_note

删除笔记。

参数:

• note_id (string): 要删除的笔记的 ID
• permanent (boolean, optional): 如果为 true，则永久删除笔记

import_markdown

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

参数:

• file_path (string): 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

🤝 贡献

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