适合谁
- 希望通过 AI 管理个人 Joplin 知识库的用户。
- 需要笔记、笔记本和标签搜索及组织能力的 MCP 客户端用户。
- 需要按笔记本限制 AI 访问范围的用户。
J
55FMRS · C
一个面向 Joplin 的非官方 MCP 服务器，功能覆盖笔记、笔记本、标签、回收站和文件导入，并提供权限控制与笔记本允许列表。运行依赖 Joplin Web Clipper 和授权令牌；涉及写入、删除、导入或网络暴露时应谨慎配置。
Joplin MCP Server 是一个基于 FastMCP 的服务器，通过 Joplin Web Clipper API 和 Python 库 joppy，让兼容 MCP 的 AI 助手访问和管理 Joplin 笔记、笔记本与标签。它提供搜索、读取、创建、编辑、组织、恢复和文件导入功能。
工具能力
find_notes
搜索笔记，支持任务筛选和回收站查询。
find_notes_with_tag
按标签查找笔记，支持任务筛选。
find_notes_in_notebook
按笔记本查找笔记，支持任务筛选。
get_all_notes
获取所有笔记，按最近更新排序；默认禁用。
get_note
按 ID 获取指定笔记。
find_in_note
在单个笔记中执行正则表达式搜索，并返回分页匹配和上下文。
get_links
提取笔记中指向其他笔记的链接。
get_note_resources
列出笔记资源，并读取图像和 PDF 的 OCR 文本。
create_note
创建笔记。
update_note
修改笔记，包括移动笔记所属笔记本。
edit_note
通过查找替换、追加或前置内容精确编辑笔记。
delete_note
删除笔记。
list_notebooks
列出可访问的笔记本。
create_notebook
创建笔记本，可指定父笔记本和表情符号图标。
update_notebook
重命名、修改图标或移动笔记本。
delete_notebook
删除笔记本。
list_tags
列出标签。
create_tag
创建标签。
update_tag
修改标签标题。
delete_tag
删除标签。
get_tags_by_note
获取指定笔记的标签。
tag_note
为一个或多个笔记添加一个或多个标签。
untag_note
从一个或多个笔记移除一个或多个标签。
restore_from_trash
恢复软删除的笔记或笔记本。
import_from_file
导入 Markdown、HTML、CSV、TXT、JEX 文件或目录。
ping_joplin
测试与 Joplin 的连接。
安装接入
在 Joplin Desktop 中打开“工具”→“选项”→“Web Clipper”，启用 Web Clipper 并复制授权令牌。安装 uv 后，使用提供的 Claude Desktop 配置，或运行 uvx --from joplin-mcp joplin-mcp-server。也可使用 pip 安装 joplin-mcp。必须设置 JOPLIN_TOKEN；可选设置 JOPLIN_URL 覆盖默认的 http://localhost:41184。配置后重启客户端。
claude_desktop_config.json
{"mcpServers":{"joplin":{"command":"uvx","args":["--from","joplin-mcp","joplin-mcp-server"],"env":{"JOPLIN_TOKEN":"your_token_here"}}}}
选型与风险
不适合谁
- 不使用 Joplin 或未启用 Web Clipper 的用户。
- 需要在没有 Joplin API 令牌的情况下运行的用户。
- 只需要只读访问且不希望配置写入、更新或导入权限的场景。
所需权限
- 需要运行中的 Joplin Web Clipper 授权令牌，并通过 JOPLIN_TOKEN 提供。
- 读取权限用于搜索、查看笔记本和标签及测试连接。
- 写入、更新、删除和导入操作可通过配置或环境变量分别控制。
- 删除笔记、笔记本和标签默认禁用；获取全部笔记和文件导入默认也禁用。
- 可使用 notebook_allowlist 按笔记本路径限制读取和写入范围。
风险与副作用
- 启用删除、更新或导入工具后，AI 可能修改或删除 Joplin 内容；删除操作默认关闭。
- 未设置笔记本允许列表时，默认可访问所有笔记本。
- 笔记搜索结果和单个笔记可能暴露内容；可通过 content_exposure 调整预览和全文显示。
- 通过 HTTP 或 SSE 公开服务时，需要自行配置反向代理和 TLS；文档建议公开暴露时使用反向代理。
- 令牌属于秘密凭据，不应公开或放入不受信任的配置中。
常见排障
- 确认 Joplin Desktop 正在运行并已启用 Web Clipper。
- 检查 JOPLIN_TOKEN 是否为当前 Joplin 实例的授权令牌。
- 默认连接地址是 http://localhost:41184；如地址不同，设置 JOPLIN_URL 或相应主机和端口配置。
- 使用 uvx 时确认已安装 uv；使用 pip 安装时确认 joplin-mcp 已安装。
- 修改客户端配置后重启 Claude Desktop、Jan AI 或相应客户端。
- 端到端测试需要运行中的 Joplin 3.x 实例；连接不可达时测试会跳过。
使用场景
搜索和阅读 Joplin 笔记。
创建会议记录或其他新笔记。
整理笔记本和标签。
恢复回收站中的笔记或笔记本。
导入 Markdown、HTML、CSV、TXT 或 JEX 内容。
支持客户端
Claude Desktop完整支持
Jan AI完整支持
OllMCP完整支持