📝 Joplin MCP 服务器

Joplin的模型上下文协议 (MCP) 服务器，支持通过模型上下文协议访问笔记。非常适合与 Claude 等 AI 助手集成。

✨ 特点

• 🔍搜索笔记：所有笔记的全文搜索

• 📖阅读笔记：检索个人笔记

• ✏️编辑笔记：创建新笔记并更新现有笔记

• 🗑️删除笔记：将笔记移至垃圾箱或永久删除

• 📥 Markdown Import ：将 Markdown 文件导入为笔记

• 🤖 AI 集成：与 Claude 和其他支持 MCP 的 AI 助手无缝集成

Related MCP server: MCP Kibela

🚀 安装

先决条件

• Python 3.10 或更高版本

• 启用了 Web Clipper 服务的Joplin 桌面

• uv （Python 包管理器）

# Clone repository
git clone https://github.com/dweigend/joplin-mcp.git
cd joplin-mcp

# Create and activate virtual environment
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
```bash
uv pip install -e .

⚙️ 配置

Joplin API 令牌

1. 打开 Joplin 桌面

2. 转到工具->选项->Web Clipper

3. 启用 Web Clipper 服务

4. 复制 API 令牌

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

JOPLIN_TOKEN=your_api_token_here

Claude 桌面设置

1. 安装 Claude Desktop

   • 下载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_mcp替换为项目的绝对路径

   重要提示：Claude Desktop 需要uv的完整路径，因为它无法访问 shell 环境变量。

🛠️ 可用工具

搜索笔记

在乔普林 (Joplin) 搜索笔记。

参数：

• query （字符串）：搜索查询

• limit （int，可选）：最大结果数（默认值：100）

获取注释

通过 ID 检索特定注释。

参数：

• note_id (字符串): 笔记的 ID

创建注释

创建新笔记。

参数：

• title （字符串）：注释标题

• body （字符串，可选）：Markdown 中的注释内容

• parent_id （字符串，可选）：父文件夹的 ID

• is_todo （布尔值，可选）：这是否是待办事项

更新说明

更新现有注释。

参数：

• note_id (字符串): 要更新的注释的 ID

• title （字符串，可选）：新标题

• body （字符串，可选）：新内容

• parent_id （字符串，可选）：新的父文件夹 ID

• is_todo （布尔值，可选）：新的待办事项状态

删除注释

删除注释。

参数：

• note_id (字符串): 要删除的注释的 ID

• permanent （布尔值，可选）：如果为真，则永久删除该注释

导入标记

将 markdown 文件导入为新笔记。

参数：

• file_path （字符串）：markdown 文件的路径

🧪 开发

调试模式

以调试模式启动服务器：

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

这将启动http://localhost:5173上的 MCP 检查器，您可以在其中测试工具。

📄 许可证

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

👤 作者

大卫·魏根德

• 网站： weigend.studio

• GitHub： @dweigend

🤝 贡献

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