Joplin

🚀 📝 Joplin MCP 服务器

这是一个为 Joplin 实现的 Model Context Protocol (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

# 安装依赖项
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 导入：导入 Markdown 文件作为笔记。
• AI 集成：与 Claude 和其他支持 MCP 的 AI 助手无缝集成。

🚀 开发

调试模式

要启用调试模式，请在配置中设置：

DEBUG=True

日志记录

默认日志级别为 INFO。要更改日志级别，请设置：

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

📄 许可证

本项目遵循 MIT License。

🎤 作者

David Weigend

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

🤝 贡献

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