🚀 📝 Joplin MCP 服务器

Joplin MCP 服务器是为 Joplin 实现的 Model Context Protocol (MCP) 服务器，借助该协议可实现笔记访问，特别适合与 Claude 等 AI 助手集成，为笔记管理与 AI 交互提供了便利。

🚀 快速开始

Joplin MCP 服务器能让你通过 MCP 协议访问 Joplin 笔记，还可与 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 文件以及与 AI 助手集成等功能。以下是部分功能的使用示例：

搜索笔记

# 搜索包含特定关键词的笔记
# 这里假设你已经配置好环境并启动了服务器
# 具体的搜索命令需要根据服务器的接口来实现
# 示例代码仅为示意
search_command "keyword"

阅读笔记

# 阅读指定 ID 的笔记
# 同样，具体命令根据接口实现
read_command note_id

高级用法

与 AI 助手集成

# 假设你已经配置好 Claude Desktop 与 MCP 服务器
# 可以在 Claude 中使用服务器提供的笔记信息
# 这里展示如何在 Claude 中调用服务器功能
# 示例代码仅为示意
claude_command "get_note_info"

📚 详细文档

可用工具

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

🤝 贡献

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