📝 Joplin MCP 服务器

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

✨ 特性

• 🔍 搜索笔记：在所有笔记中进行全文搜索
• 📖 阅读笔记：检索单个笔记
• ✏️ 编辑笔记：创建新笔记并更新现有笔记
• 🗑️ 删除笔记：将笔记移动到回收站或永久删除
• 📥 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

🤝 贡献

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