Joplin MCP Server

Joplin MCP 服务

一个基于 FastMCP 的 Model Context Protocol（MCP）服务，通过 Python API joppy 集成 Joplin 笔记应用，让 AI 助手能够通过标准化接口与 Joplin 笔记、笔记本和标签交互。

目录

• 你可以做什么
• 快速开始
• 支持的客户端
• 使用示例
• 工具权限
• 笔记本允许列表
• 高级配置
• Docker
• 项目结构
• 测试
• 完整工具参考
• 更新日志

你可以做什么

此 MCP 服务提供 26 个经过优化的工具，全面集成 Joplin：

笔记管理

• 查找与搜索：find_notes（支持使用 trash=True 查找已移至废纸篓的笔记）、find_notes_with_tag、find_notes_in_notebook、get_all_notes
• CRUD 操作：get_note、get_note_resources（读取附件图片/PDF 中的 OCR 文本）、get_links、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

快速开始

1. 打开 Joplin Desktop → Tools → Options → Web Clipper
2. 启用 Web Clipper 服务
3. 复制授权令牌
4. 设置你偏好的客户端

支持的客户端

任何兼容 MCP 的客户端都应该可以使用。以下列出了提供了设置说明的客户端。

Claude Desktop

运行自动安装程序：

# Install and configure everything automatically (pip)
pip install joplin-mcp
joplin-mcp-install

# Or use zero-install with uvx (recommended if you have uv)
uvx --from joplin-mcp joplin-mcp-install

# Optional: pin a specific version/range for stability
uvx --from joplin-mcp==0.4.1 joplin-mcp-install
uvx --from 'joplin-mcp>=0.4,<0.5' joplin-mcp-install

此脚本将：

• 配置 Joplin API 令牌
• 设置工具权限（创建/更新/删除）
• 自动设置 Claude Desktop
• 测试连接

设置完成后，重启 Claude Desktop 即可开始使用！

Claude Code

安装编排插件，以便更智能地使用工具（编辑与更新、读取长笔记、批量添加标签）：

/plugin marketplace add alondmnt/joplin-mcp
/plugin install joplin-mcp

首次使用时，系统会提示你输入 Joplin API 令牌。使用 Joplin 工具时会自动调用此技能，也可以通过 /joplin 手动调用。

Jan AI

1. 从 https://jan.ai 安装 Jan AI

2. 在 Jan 的界面中添加 MCP 服务：

   • 打开 Jan AI
   • 前往 Settings → Extensions → Model Context Protocol
   • 点击 Add MCP Server
   • 配置：
     • Name：joplin
     • Command：uvx --from joplin-mcp joplin-mcp-server （需要安装 uv）
     • Environment Variables：
       • JOPLIN_TOKEN：your_joplin_api_token_here
   • 启用此服务

3. 开始聊天，即可访问你的 Joplin 笔记！

自动设置（替代方案）

# Install and configure Jan AI automatically (if Jan is already installed)
pip install joplin-mcp
joplin-mcp-install

此脚本会自动检测并配置 Jan AI，就像 Claude Desktop 一样。

OllMCP（本地 Ollama 模型）

自动发现（如果你已先设置 Claude Desktop）

# Install ollmcp
pip install ollmcp

# Run with auto-discovery (requires existing Claude Desktop config)
ollmcp --auto-discovery --model qwen3:4b

手动设置（可独立使用）

# Install ollmcp
pip install ollmcp

# Set environment variable
export JOPLIN_TOKEN="your_joplin_api_token_here"

# Run with uvx (requires uv installed)
ollmcp --server "joplin:uvx --from joplin-mcp joplin-mcp-server" --model qwen3:4b

# Or with an installed package (pip install joplin-mcp)
ollmcp --server "joplin:joplin-mcp-server" --model qwen3:4b

使用示例

完成配置后，你可以向 AI 助手提出以下请求：

• “列出我的所有笔记本” - 查看 Joplin 的组织结构
• “查找有关 Python 编程的笔记” - 搜索你的知识库
• “为今天的站会创建一条会议笔记” - 快速创建笔记
• “将我最近的 AI 笔记标记为‘重要’” - 使用标签整理
• “显示我的待办事项” - 使用 find_notes(task=True) 查找任务条目

工具权限

安装脚本提供 4 个权限级别：

• 读取（始终启用）：安全地浏览和搜索笔记
• 写入（可选）：创建新笔记、笔记本和标签
• 更新（可选）：修改现有内容
• 删除（可选）：永久移除内容

请选择符合你偏好和使用场景的级别。

笔记本允许列表

使用基于模式的访问控制，将 AI 的访问限制为特定笔记本。配置后，只有匹配的笔记本（及其内容）可见，所有其他笔记本均会隐藏。

快速设置

JSON 配置（joplin-mcp.json）：

{
  "token": "your_token",
  "notebook_allowlist": ["Work", "Projects/Public"]
}

环境变量：

export JOPLIN_NOTEBOOK_ALLOWLIST="Work,Projects/Public"

模式语法

模式遵循 gitignore/gitwildmatch 语义：

模式	匹配内容	示例
Work	笔记本名称完全匹配（及其所有子项）	Work、Work/Tasks、Work/Notes
Projects/*	Projects 的直接子项	Projects/Alpha、Projects/Beta
Projects/**	递归匹配所有后代项	Projects/Alpha/Tasks/Q1
!Projects/Secret	排除（取反）特定路径	Projects 中除 Secret 之外的所有内容

否定模式始终优先于正向模式（路径或其祖先匹配任何否定模式时，都会拒绝访问）。

工作原理

• 分层访问：允许访问父笔记本，即可访问其所有子项。允许访问 Projects，也就能访问 Projects/Work/Tasks 中的笔记。
• 读取保护：get_note、get_note_resources、find_notes、get_links — 被屏蔽笔记本中的笔记会被过滤或拒绝访问。
• 写入保护：create_note、update_note、edit_note、delete_note — 对被屏蔽笔记本中的笔记执行的操作会被拒绝。
• 笔记本操作：list_notebooks 只会显示可访问的笔记本。设置允许列表后，在被屏蔽的父笔记本下创建笔记本，以及在顶层（无 parent_name）创建笔记本，都会被拒绝；update_notebook 在相同策略下也会拒绝将笔记本移至顶层（parent_name="/"）——这两种操作都会让 Agent 悄无声息地将笔记本移出允许列表限定范围。若要扩展允许列表，请在 Joplin UI 中创建或移动笔记本，然后将其添加到 notebook_allowlist 并重启服务。
• 搜索过滤：find_notes 的结果会经过过滤，只包含位于可访问笔记本中的笔记。
• 标签操作：tag_note、untag_note、get_tags_by_note 会对笔记所在的笔记本执行访问控制。
• 错误隐私：访问被屏蔽的内容会引发通用的“Notebook not accessible”错误，不会透露笔记本名称或 ID。

配置示例

仅专注于单个项目（笔记本名称包含空格）：

{ "notebook_allowlist": ["Work Projects"] }

多个笔记本并排除特定项：

{ "notebook_allowlist": ["Projects", "!Projects/Secret", "AI", "Reference"] }

Glob 模式：

{ "notebook_allowlist": ["Projects/*", "!Projects/Private"] }

不设置允许列表（默认） — 可访问所有笔记本：

{ "notebook_allowlist": null }

启动行为

服务启动时会验证允许列表并记录日志：

• 每个条目都会与现有笔记本进行匹配
• 无法解析的模式会触发警告（但不会阻止启动）
• 如果允许列表未匹配到任何可访问的笔记本，则会记录警告

---

高级配置

开发环境安装

适用于开发者或希望使用最新功能的用户：

git clone https://github.com/alondmnt/joplin-mcp.git
cd joplin-mcp
python bootstrap.py

bootstrap.py 跨平台运行：它会询问是否创建 ./venv，运行 pip install -e .，然后启动交互式安装程序。传入 --no-venv 可将其安装到当前已激活的 Python 环境中。

手动配置

如果你更倾向于手动设置，或脚本无法运行：

关于 uvx 的说明：uvx 可运行 Python 应用，无需永久安装（需要 uv：pip install uv）。它可以读取和写入用户配置文件（例如 Claude/Jan 配置），因此 uvx --from joplin-mcp joplin-mcp-install 和通过 pip 安装一样可用于设置。

固定版本（可选）：对于长期使用的客户端配置或 CI，可以固定版本或限制版本范围，以确保可复现性，例如 uvx --from joplin-mcp==0.4.1 joplin-mcp-install 或 uvx --from 'joplin-mcp>=0.4,<0.5' joplin-mcp-install。

1. 创建配置文件

在项目目录中创建 joplin-mcp.json：

{
  "token": "your_api_token_here",
  "host": "localhost", 
  "port": 41184,
  "timeout": 30,
  "verify_ssl": false
}

2. Claude Desktop 配置

添加到 claude_desktop_config.json：

选项 A：使用 uvx（无需安装）

{
  "mcpServers": {
    "joplin": {
      "command": "uvx",
      "args": ["--from", "joplin-mcp", "joplin-mcp-server"],
      "env": {
        "JOPLIN_TOKEN": "your_token_here"
      }
    }
  }
}

需要安装 uv：pip install uv

选项 B：使用已安装的软件包

{
  "mcpServers": {
    "joplin": {
      "command": "joplin-mcp-server",
      "env": {
        "JOPLIN_TOKEN": "your_token_here"
      }
    }
  }
}

3. 更多客户端配置示例

如需了解更多客户端配置，包括不同的传输选项（HTTP、SSE、Streamable HTTP），请参阅 client-config.json.example。

此文件包含以下配置：

• STDIO 传输（默认，兼容性最佳）
• HTTP 传输（基本 HTTP 服务模式）
• SSE 传输（推荐用于 gemini-cli 和 OpenAI 客户端）
• Streamable HTTP 传输（适用于高级 Web 客户端）
• HTTP-compat 传输（在现代 /mcp JSON-RPC 与旧版 /sse//messages 客户端之间建立桥接）

工具权限配置

通过编辑配置，精细控制 AI 可以执行的操作：

{
  "tools": {
    "create_note": true,
    "update_note": true,
    "delete_note": false,
    "create_notebook": true,
    "update_notebook": false,
    "delete_notebook": false,
    "create_tag": true,
    "update_tag": false,
    "delete_tag": false,
    "get_all_notes": false,
    "import_from_file": true
  }
}

环境变量

可代替 JSON 配置文件使用，也可与其同时使用：

# Connection settings
export JOPLIN_TOKEN="your_api_token_here"
export JOPLIN_HOST="localhost"
export JOPLIN_PORT="41184"
export JOPLIN_TIMEOUT="30"

环境变量会逐项覆盖配置文件中的键，因此 MCP 客户端配置中的 env 块优先于服务发现的任何文件。只有实际设置的变量才会生效，因此 设置某个变量不会影响文件中的其余设置。完整优先级：直接 参数 > 环境变量 > 配置文件 > 默认值。

按工具设置环境变量

每个工具都可以通过 JOPLIN_TOOL_<NAME>=true|false 单独启用或禁用。其优先级高于配置文件中的设置。

环境变量	默认值
JOPLIN_TOOL_FIND_NOTES	true
JOPLIN_TOOL_FIND_NOTES_WITH_TAG	true
JOPLIN_TOOL_FIND_NOTES_IN_NOTEBOOK	true
JOPLIN_TOOL_FIND_IN_NOTE	true
JOPLIN_TOOL_GET_ALL_NOTES	false
JOPLIN_TOOL_GET_NOTE	true
JOPLIN_TOOL_GET_LINKS	true
JOPLIN_TOOL_CREATE_NOTE	true
JOPLIN_TOOL_UPDATE_NOTE	true
JOPLIN_TOOL_EDIT_NOTE	true
JOPLIN_TOOL_DELETE_NOTE	false
JOPLIN_TOOL_LIST_NOTEBOOKS	true
JOPLIN_TOOL_CREATE_NOTEBOOK	true
JOPLIN_TOOL_UPDATE_NOTEBOOK	false
JOPLIN_TOOL_DELETE_NOTEBOOK	false
JOPLIN_TOOL_LIST_TAGS	true
JOPLIN_TOOL_CREATE_TAG	true
JOPLIN_TOOL_UPDATE_TAG	false
JOPLIN_TOOL_DELETE_TAG	false
JOPLIN_TOOL_GET_TAGS_BY_NOTE	true
JOPLIN_TOOL_TAG_NOTE	true
JOPLIN_TOOL_UNTAG_NOTE	true
JOPLIN_TOOL_PING_JOPLIN	true
JOPLIN_TOOL_RESTORE_FROM_TRASH	true
JOPLIN_TOOL_IMPORT_FROM_FILE	false

笔记本允许列表环境变量

环境变量	默认值	说明
JOPLIN_NOTEBOOK_ALLOWLIST	（未设置）	以逗号分隔的笔记本模式列表（例如：Work,Projects/*,!Projects/Secret）。未设置表示不限制；设置为空值则会拒绝所有笔记本

HTTP 传输支持

该服务支持 STDIO 和 HTTP 两种传输方式：

# STDIO (default)
joplin-mcp-server --config ~/.joplin-mcp.json

# HTTP transport (development, from repo)
PYTHONPATH=src python -m joplin_mcp.server --transport http --port 8000 --config ./joplin-mcp.json

# Opt-in HTTP compatibility bundle (modern + legacy SSE endpoints)
PYTHONPATH=src python -m joplin_mcp.server --transport http-compat --port 8000 --config ./joplin-mcp.json
# or keep --transport http and export MCP_HTTP_COMPAT=1/true to toggle the same behavior.

HTTP 客户端配置

注意：Claude Desktop 目前使用 STDIO 传输，不会直接使用 HTTP/SSE 配置。以下示例适用于支持网络传输的客户端。

{
  "mcpServers": {
    "joplin": {
      "transport": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

配置参考

基本设置

选项	默认值	描述
token	required	Joplin API 身份验证令牌
host	localhost	Joplin 服务主机名
port	41184	Joplin Web Clipper 端口
timeout	30	请求超时时间（秒）
verify_ssl	false	SSL 证书验证

工具权限

选项	默认值	描述
tools.create_note	true	允许创建新笔记
tools.update_note	true	允许修改现有笔记
tools.edit_note	true	允许进行精确编辑（查找/替换、追加、前置插入）
tools.delete_note	false	允许删除笔记（默认禁用——具有破坏性）
tools.create_notebook	true	允许创建新笔记本
tools.update_notebook	false	允许修改笔记本标题和表情符号图标
tools.delete_notebook	false	允许删除笔记本（默认禁用——具有破坏性）
tools.create_tag	true	允许创建新标签
tools.update_tag	false	允许修改标签标题
tools.delete_tag	false	允许删除标签（默认禁用——具有破坏性）
tools.tag_note	true	允许为笔记添加标签
tools.untag_note	true	允许从笔记中移除标签
tools.restore_from_trash	true	允许恢复软删除的笔记或笔记本
tools.find_notes	true	允许在笔记中进行文本搜索（支持按任务筛选）
tools.find_notes_with_tag	true	允许按标签查找笔记（支持按任务筛选）
tools.find_notes_in_notebook	true	允许按笔记本查找笔记（支持按任务筛选）
tools.find_in_note	true	允许在单篇笔记中进行正则表达式搜索
tools.get_all_notes	false	允许获取所有笔记（默认禁用——可能占满上下文窗口）
tools.get_note	true	允许获取指定笔记
tools.get_note_resources	true	允许读取笔记的资源及其 OCR 文本
tools.get_links	true	允许提取指向其他笔记的链接
tools.list_notebooks	true	允许列出所有笔记本
tools.list_tags	true	允许列出所有标签
tools.get_tags_by_note	true	允许获取指定笔记的标签
tools.ping_joplin	true	允许测试服务连通性
tools.import_from_file	false	允许导入文件/目录（MD、HTML、CSV、TXT、JEX）

笔记本允许列表

选项	默认值	描述
notebook_allowlist	null	允许访问的笔记本模式列表。null = 不作限制。支持 gitignore 风格的模式：精确名称、* 通配符、** 递归匹配、! 否定

内容暴露（隐私设置）

选项	默认值	描述
content_exposure.search_results	"preview"	所有搜索和列表结果中的内容可见性："none"、"preview"、"full"
content_exposure.individual_notes	"full"	单条笔记的内容可见性："none"、"preview"、"full"
content_exposure.max_preview_length	300	内容预览的最大长度（字符数）
content_exposure.smart_toc_threshold	2000	超过此长度的笔记将显示目录，而不是完整正文
content_exposure.enable_smart_toc	true	关闭目录回退机制，以始终返回完整笔记正文
content_exposure.output_hints	false	在结果中附带可执行的后续调用提示（NEXT_STEPS、NEXT_PAGE）。对较小模型很有用，但对能力较强的模型会造成重复

降低 max_preview_length 和 smart_toc_threshold，或将 search_results 设为 "none"，是减少会话消耗 Token 数量的主要方法。 list_notebooks 和 list_tags 只返回 Agent 会用到的字段；传入 verbose=True 可获取图标、父级 ID 和 时间戳。请参阅 docs/content-privacy.md。

Docker

在容器中运行 MCP 服务。默认传输方式为 HTTP，以确保广泛兼容；可通过环境变量切换。

构建

docker build -t joplin-mcp .

运行（默认使用 HTTP）

docker run --rm \
  -p 8000:8000 \
  -e JOPLIN_TOKEN=your_api_token \
  joplin-mcp

挂载配置运行

docker run --rm \
  -p 8000:8000 \
  -v $PWD/joplin-mcp.json:/config/joplin-mcp.json:ro \
  joplin-mcp

选择传输方式

• SSE（流式传输）：-e MCP_TRANSPORT=sse
• Streamable HTTP：-e MCP_TRANSPORT=streamable-http
• STDIO（无端口）：-e MCP_TRANSPORT=stdio

示例（SSE）：

docker run --rm \
  -p 8000:8000 \
  -e JOPLIN_TOKEN=your_api_token \
  -e MCP_TRANSPORT=sse \
  joplin-mcp

容器默认监听 0.0.0.0:8000。如果要公开访问，请将其置于反向代理之后，并在代理处终止 TLS。对于 SSE，请确保代理的持久连接和缓冲配置正确。

项目结构

• src/joplin_mcp/ - 主包目录
  • fastmcp_server.py - 服务实现，包含 26 个工具和 Pydantic 验证类型
  • config.py - 配置管理（包括笔记本允许列表）
  • notebook_utils.py - 笔记本路径解析、允许列表匹配和缓存
  • server.py - 服务入口（模块和 CLI）
  • tools/ - 工具实现（笔记、笔记本、标签）
  • ui_integration.py - UI 集成工具
• docs/ - 文档（故障排除、隐私控制、增强提案）
• tests/ - 单元测试套件
• tests/e2e/ - 通过 Web Clipper API 对真实 Joplin Desktop（3.x）执行的端到端测试；请参阅“运行测试”

测试

测试连接：

# For pip install
joplin-mcp-server --config ~/.joplin-mcp.json

# For development (from repo)
PYTHONPATH=src python -m joplin_mcp.server --config ./joplin-mcp.json

你应该会看到：

Starting Joplin FastMCP Server...
Successfully connected to Joplin!
Found X notebooks, Y notes, Z tags
FastMCP server starting...
Available tools: 26 tools ready

运行测试

# Unit tests (no Joplin instance required)
pytest tests/ --ignore=tests/e2e

# E2E tests (requires a running Joplin instance)
JOPLIN_TOKEN=your_api_token \
JOPLIN_HOST=localhost \
JOPLIN_PORT=41184 \
pytest tests/e2e/ -v -m e2e --override-ini="addopts="

E2E 测试套件通过 Web Clipper API 与真实的 Joplin Desktop 通信，并测试包括笔记本允许列表强制执行在内的每个工具。如果无法访问 JOPLIN_HOST:JOPLIN_PORT，该套件会跳过自身运行，因此可以安全地与单元测试一同运行。需要 Joplin 3.x（垃圾箱架构在 3.0 中引入；较早版本会因 no such column: deleted_time 而失败）。

完整工具参考

工具	权限	描述
查找笔记
find_notes	读取	在所有笔记中进行全文搜索（支持按任务筛选；使用 trash=True 和 query="*" 可列出已移入回收站的笔记）
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	更新	重命名、更改表情符号图标，或将笔记本移至另一个父级笔记本下（或通过 parent_name="/" 移至顶层）
delete_notebook	删除	删除笔记本
管理标签
list_tags	读取	查看所有可用标签
create_tag	写入	创建新标签
update_tag	更新	修改标签标题
delete_tag	删除	删除标签
get_tags_by_note	读取	列出指定笔记上的标签
标签与笔记的关联
tag_note	更新	为一个或多个笔记添加一个或多个标签（接受列表）
untag_note	更新	从一个或多个笔记中移除一个或多个标签（接受列表）
回收站管理
restore_from_trash	更新	恢复软删除的笔记或笔记本（传入 item_type='note' 或 'notebook'）
导入工具
import_from_file	写入	导入文件/目录（MD、HTML、CSV、TXT、JEX）
系统工具
ping_joplin	读取	测试连接状态