Joplin 笔记应用的模型上下文协议（MCP）服务器。

由 belsar.ai 设计，安装简便且使用愉快。

视频

https://www.youtube.com/watch?v=B3qJa7ycqNM&t=6s

平台支持

可在macOS和Linux上使用。Windows用户应使用WSL2。

建筑

默认情况下，该MCP服务器会暴露两个工具：

• execute_joplin_readonly_script：用于只读模式运行脚本（检查/阅读笔记和笔记本）。
• execute_joplin_script：用于运行既能执行修改、创建或删除的脚本。

这种基于脚本的执行模式遵循了 Anthropic 推荐的 MCP 服务器模式，是目前构建 MCP 服务器最高效、最高效的方式。

脚本在操作系统层面由Anthropic Sandbox Runtime隔离的独立运行程序中执行。node:vm 限制该进程内可用的全局程序;沙盒运行时是阻止网络访问和文件系统写入的安全边界。

运行者调用joplin.*方法时就像直接与Joplin通信一样，但所有请求都经过该代理，而代理只允许特定的一组API方法。

joplin-mcp

Model Context Protocol (MCP) server for the Joplin note-taking app.

Designed by belsar.ai to be easy to install & enjoyable to use.

Video

https://www.youtube.com/watch?v=B3qJa7ycqNM&t=6s

Platform Support

Available on macOS and Linux. Windows users should use WSL2.

Architecture

By default, this MCP server exposes two tools:

• execute_joplin_readonly_script: For running scripts in read-only mode (inspecting/reading notes and notebooks).
• execute_joplin_script: For running scripts that can also perform modifications, creations, or deletions.

This script-based execution pattern follows Anthropic’s recommended pattern for MCP servers and is the most performant, token-efficient way to build an MCP server today.

Scripts execute in a separate runner process isolated at the OS level by Anthropic Sandbox Runtime. node:vm limits the globals available inside that process; the Sandbox Runtime is the security boundary that blocks network access and filesystem writes.

joplin api ←http→ broker (allowlisted proxy) ←stdio→ runner (sandboxed)

The runner calls joplin.* methods as if talking to Joplin directly, but all requests pass through the broker, which only permits a specific set of API methods. The broker is the only piece that can interact with your notes — and nothing else.

Quick Start

1. Open Joplin & navigate to tools > web clipper > enable web clipper service
2. The Joplin app needs to remain running (minimized is fine)
3. Add the server to your MCP client:

Claude Code:

claude mcp add --scope user --transport stdio joplin -- npx -y @belsar-ai/joplin-mcp

Codex:

codex mcp add joplin -- npx -y @belsar-ai/joplin-mcp

Agy: add this entry to ~/.gemini/config/mcp_config.json (or configure the same stdio server through /mcp):

{
  "mcpServers": {
    "joplin": {
      "command": "npx",
      "args": ["-y", "@belsar-ai/joplin-mcp"]
    }
  }
}

4. That’s it. Send a test request like “Find my notes about installing Fedora linux”.

Linux Requirements

Install the following system packages before first use:

# Fedora
sudo dnf install bubblewrap socat ripgrep

# Ubuntu/Debian
sudo apt install bubblewrap socat ripgrep

The server will fail with an error message if these are missing.

Uninstall

claude mcp remove joplin

codex mcp remove joplin

agy mcp remove joplin

Configuration (Optional)

Notebook Scope Config

Create .mcp-config/joplin-mcp.toml in your project root to scope which notebooks are visible:

[defaults]
notebook = "Notes"

[scope]
notebooks = ["Notes", "Software"]

• defaults.notebook: Where new notes go if you don’t specify a notebook
• scope.notebooks: Only these notebooks are visible to the AI