乔普林服务器MCP
什么是Joplin服务器？
注： 此MCP服务器连接到 乔普林服务器 REST API，而不是Joplin桌面Web Clipper。 乔普林云： 应该与 JOPLIN_SERVER_URL=https://joplincloud.com，但这还没有经过测试。如果你尝试一下，请用你的结果打开一个问题。工具
| 工具 | 说明 |
|---|---|
ping_joplin | 检查服务器连接 |
list_notebooks | 列出所有笔记本 |
get_notebook | 通过笔记和子笔记本获取笔记本详细信息 |
create_notebook | 创建新笔记本 |
update_notebook | 重命名或移动笔记本（使用循环引用检查） |
delete_notebook | 删除笔记本（非空时可选择强制） |
list_notes | 列出笔记，可选择按笔记本筛选 |
get_all_notes | 使用分页、排序和笔记本过滤器获取所有笔记 |
search_notes | 按标题或正文中的文本搜索笔记 |
get_note | 获取注释文本（资源引用替换为名称） |
get_notes_batch | 一次阅读多个笔记（最多50个，并行） |
get_note_full | 以base64格式嵌入所有资源以获取注释 |
create_note | 创建新笔记 |
export_note | 将注释导出为markdown，资源导出为base64块 |
update_note | 更新笔记标题、正文或移动到另一个笔记本 |
delete_note | 删除注释 |
list_tags | 列出所有标签 |
create_tag | 创建新标签 |
delete_tag | 删除标签 |
get_note_tags | 列出分配给笔记的标签 |
add_tag_to_note | 在笔记中添加标签 |
remove_tag_from_note | 从笔记中删除标签 |
get_note_resources | 列出附在注释中的资源 |
get_resource_info | 获取资源元数据 |
download_resource | 以base64格式下载资源 |
设置
先决条件
- 用户凭据（电子邮件+密码）
环境变量
| 变量 | 必填 | 默认 | 描述 |
|---|---|---|---|
JOPLIN_SERVER_URL | 是 | -- | Joplin服务器URL |
JOPLIN_EMAIL | 是 | -- | 用户电子邮件 |
JOPLIN_PASSWORD | 是 | -- | 用户密码 |
MCP_TRANSPORT | 没有 | stdio | 运输： stdio 或 sse |
MCP_HOST | 没有 | 0.0.0.0 | SSE监听主机 |
MCP_PORT | 没有 | 8081 | SSE监听端口 |
使用Docker运行
docker run -d \
-e JOPLIN_SERVER_URL=https://your-joplin-server.example.com \
-e JOPLIN_EMAIL=your@email.com \
-e JOPLIN_PASSWORD=your_password \
-p 8081:8081 \
alexfail2/joplin-mcp集装箱默认为SSE运输。端点将在以下位置可用 http://localhost:8081/sse.
在本地运行（stdio）
pip install mcp httpx
python app/server.py从源代码构建
docker build -t joplin-mcp .MCP客户端配置
SSE（Docker）
{
"mcpServers": {
"joplin": {
"url": "http://localhost:8081/sse"
}
}
}stdio（本地）
{
"mcpServers": {
"joplin": {
"command": "python",
"args": ["/path/to/app/server.py"],
"env": {
"JOPLIN_SERVER_URL": "https://your-joplin-server.example.com",
"JOPLIN_EMAIL": "your@email.com",
"JOPLIN_PASSWORD": "your_password"
}
}
}
}运作原理
服务器通过电子邮件/密码会话与Joplin server进行身份验证，并使用2分钟的TTL缓存构建所有项目（笔记、笔记本、标签）的内存索引。增量同步比较服务器端 updated_time 使用缓存的etags，只获取更改的项目（典型的刷新：~5s vs ~35s完全重建）。索引被持久化到磁盘，因此容器可以立即重新启动。资源元数据在首次访问时延迟加载。后台刷新使索引保持最新，而不会阻止请求。在API调用之前验证所有ID（32-char十六进制）。
Joplin的内部序列化格式（标题+标记体+元数据块）被解析并呈现为干净的结构化输出。