joplin-mcp-server

Joplin MCP 服务

这是一个专为 Joplin 打造的独立 MCP（Model Context Protocol）服务。它将 Joplin Terminal CLI 作为依赖打包，无需桌面应用、全局安装或管理外部进程。通过自动协商端口，可与 Joplin Desktop 共存。

快速开始

npx joplin-mcp-server --token your_joplin_token

就是这么简单。服务会启动自己的 Joplin Terminal 实例（sidecar 模式），同步到你配置的后端，并通过 MCP 提供你的笔记。

架构

Sidecar 模式（默认）

服务将 joplin 作为 npm 依赖打包，并管理自己的 Joplin Terminal 进程。无需 Joplin 桌面应用——sidecar 会处理所有事务：数据存储、同步和 REST API。

如果 Joplin Desktop 已在运行，sidecar 会自动找到可用端口（扫描 41184-41193），并与其并行运行。如果配置了相同的同步目标，两个实例会保持同步。

# Basic usage — sidecar starts automatically
npx joplin-mcp-server --token your_token

# With cloud sync
npx joplin-mcp-server --token your_token \
  --sync-target joplin-cloud \
  --sync-username [email protected] --sync-password pass

# With filesystem sync (e.g. OneDrive folder)
npx joplin-mcp-server --token your_token \
  --sync-target filesystem \
  --sync-path /mnt/c/Users/you/OneDrive/Joplin

Joplin CLI 按以下顺序查找：JOPLIN_CLI 环境变量 > node_modules/.bin/joplin（打包版本）> 全局安装 > npx 回退方案。

默认情况下，数据存储在 ~/.config/joplin-mcp 中（与任何 Joplin 桌面版安装相互独立）。

外部模式

连接到现有的 Joplin 实例，而不是启动 sidecar。设置 JOPLIN_HOST 或 JOPLIN_PORT 即可启用。

# Connect to Joplin desktop on another machine or Windows host
JOPLIN_HOST=192.168.0.40 JOPLIN_PORT=41184 npx joplin-mcp-server --token your_token

配置

环境变量

变量	描述	默认值
JOPLIN_TOKEN	API 令牌（必需）	--
JOPLIN_HOST	连接到此主机上的现有 Joplin（跳过 sidecar）	--
JOPLIN_PORT	连接到此端口上的现有 Joplin（跳过 sidecar）	--
JOPLIN_CLI	joplin CLI 二进制文件的路径（覆盖自动检测）	--
JOPLIN_PROFILE	sidecar 模式下的 Joplin 数据目录	~/.config/joplin-mcp
JOPLIN_SYNC_TARGET	同步目标类型	none
JOPLIN_SYNC_PATH	同步目标 URL/路径	--
JOPLIN_SYNC_USERNAME	同步用户名/邮箱	--
JOPLIN_SYNC_PASSWORD	同步密码	--
JOPLIN_SYNC_REGION	S3 区域	us-east-1
JOPLIN_SYNC_ENDPOINT	S3 端点 URL（适用于非 AWS 服务商）	AWS S3
JOPLIN_SYNC_FORCE_PATH_STYLE	使用路径风格的 S3 URL（true/false）	false
LOG_LEVEL	日志级别：debug、info、warn、error	info

命令行选项

OPTIONS:
  --env-file <file>          Load environment variables from file
  --token <token>            Joplin API token
  --transport <type>         Transport type: stdio (default) or http
  --http-port <port>         HTTP server port (default: 3000, only with --transport http)
  --profile <dir>            Joplin data directory (default: ~/.config/joplin-mcp)
  --sync-target <type>       Sync target: none, filesystem, webdav, nextcloud,
                             joplin-cloud, joplin-server, s3, dropbox, onedrive
  --sync-path <url>          URL or path for sync target
  --sync-username <user>     Username/email for sync
  --sync-password <pass>     Password for sync
  --help, -h                 Show help message

路径展开

--profile 选项和 filesystem 同步目标的 --sync-path 支持 ~ 和环境变量展开，以兼容跨平台。其他目标的 --sync-path 接受 URL 或存储桶名称，因此会原样传递：

# Tilde expands to home directory (Linux, macOS, Windows)
--sync-path ~/OneDrive/Apps/Joplin

# Environment variables (both forms supported)
--sync-path ${HOME}/OneDrive/Apps/Joplin
--sync-path $HOME/OneDrive/Apps/Joplin

# Windows example using USERPROFILE
--sync-path ${USERPROFILE}/OneDrive/Apps/Joplin

这适用于 MCP 客户端配置（.mcp.json、Claude Desktop），这些环境中无法使用 shell 展开。

WSL 自动检测： 在 WSL 上，如果 ~/ 路径为空或不存在，服务会自动检查对应的 Windows 路径 /mnt/c/Users/<user>/...。这意味着在 WSL 上直接使用 --sync-path ~/OneDrive/Apps/Joplin 即可，无需填写完整的 /mnt/c/... 路径。

同步目标

目标	必需选项
none	（默认，不同步）
filesystem	--sync-path /path/to/dir
webdav	--sync-path <url> --sync-username --sync-password
nextcloud	--sync-path <url> --sync-username --sync-password
joplin-cloud	--sync-username --sync-password
joplin-server	--sync-path <url> --sync-username --sync-password
s3	--sync-path <bucket> --sync-username <access-key> --sync-password <secret-key>
dropbox	（OAuth 流程）
onedrive	（OAuth 流程）

兼容 S3 的服务提供商

s3 目标默认使用 AWS（https://s3.amazonaws.com/，区域 us-east-1）。使用 --sync-region 和 --sync-endpoint，即可将其指向任意兼容 S3 的服务提供商：

# Backblaze B2
joplin-mcp-server --token my_token \
  --sync-target s3 --sync-path my-bucket \
  --sync-region us-west-004 \
  --sync-endpoint https://s3.us-west-004.backblazeb2.com \
  --sync-username <access-key> --sync-password <secret-key>

# MinIO / self-hosted: path-style URLs are usually required
joplin-mcp-server --token my_token \
  --sync-target s3 --sync-path my-bucket \
  --sync-endpoint https://minio.example.com \
  --sync-force-path-style true \
  --sync-username <access-key> --sync-password <secret-key>

Cloudflare R2 和 Wasabi 的配置方式相同：将 --sync-endpoint 设置为服务提供商的 S3 端点。

MCP 客户端配置

Claude Code

此仓库包含一个 .mcp.json，可与 Claude Code 的环境变量展开功能配合使用：

{
  "mcpServers": {
    "joplin": {
      "command": "node",
      "args": ["dist/bin.js"],
      "env": {
        "JOPLIN_TOKEN": "${JOPLIN_TOKEN}"
      }
    }
  }
}

在 shell 中设置 JOPLIN_TOKEN（将其添加到 ~/.bashrc 或 ~/.zshrc）：

export JOPLIN_TOKEN="your_actual_token_here"

Claude Desktop

Claude Desktop 不支持 ${VAR} 展开。请直接提供值：

{
  "mcpServers": {
    "joplin": {
      "command": "npx",
      "args": ["joplin-mcp-server", "--token", "your_actual_token_here"]
    }
  }
}

启用同步（Claude Desktop）

{
  "mcpServers": {
    "joplin": {
      "command": "npx",
      "args": [
        "joplin-mcp-server",
        "--token",
        "your_token",
        "--sync-target",
        "filesystem",
        "--sync-path",
        "/path/to/sync/dir"
      ]
    }
  }
}

外部模式

{
  "mcpServers": {
    "joplin": {
      "command": "npx",
      "args": ["joplin-mcp-server"],
      "env": {
        "JOPLIN_TOKEN": "your_actual_token_here",
        "JOPLIN_HOST": "192.168.0.40",
        "JOPLIN_PORT": "41184"
      }
    }
  }
}

Docker

docker build -t joplin-mcp .
docker run -e JOPLIN_TOKEN=your_token -p 3000:3000 joplin-mcp

WSL 设置

在 WSL 中运行？旁路架构让设置变得简单，无需进行 Windows 端口转发。服务会自动检测 WSL，并处理 Linux 和 Windows 文件系统之间的路径解析。

通过 OneDrive 进行文件系统同步（推荐）

Windows 上的 Joplin 桌面应用和 WSL 旁路进程都会同步到同一个 OneDrive 文件夹。它们可以看到相同的笔记，无需直接相互通信。

# Uses ~/OneDrive — automatically resolves to /mnt/c/Users/YourName/OneDrive on WSL
npx joplin-mcp-server --token your_token \
  --sync-target filesystem \
  --sync-path ~/OneDrive/Apps/Joplin

# Or specify the Windows path explicitly
npx joplin-mcp-server --token your_token \
  --sync-target filesystem \
  --sync-path /mnt/c/Users/YourName/OneDrive/Apps/Joplin

在 Joplin 桌面应用中，将同步配置为使用同一个 OneDrive 文件夹：工具 > 选项 > 同步 > 文件系统 > /Users/YourName/OneDrive/Apps/Joplin

与 Joplin Desktop 共存： 如果 Desktop 在端口 41184 上运行，旁路进程会自动使用下一个可用端口。启动时会记录一条警告，提醒你两个实例使用不同的数据库，且需要使用相同的同步目标才能保持同步。

云同步

或者，两个实例也可以同步到 Joplin Cloud 或其他云后端：

npx joplin-mcp-server --token your_token \
  --sync-target joplin-cloud \
  --sync-username [email protected] --sync-password pass

外部模式（端口转发）

如果你更愿意直接连接到 Windows 上的 Joplin，而不是运行旁路进程：

在 Windows 上（以管理员身份运行 PowerShell）：

netsh interface portproxy add v4tov4 listenport=41184 listenaddress=0.0.0.0 connectport=41184 connectaddress=127.0.0.1

在 WSL 中：

JOPLIN_HOST=192.168.0.40 JOPLIN_PORT=41184 npx joplin-mcp-server --token your_token

在 Windows 上使用 ipconfig，或在 WSL 中运行 cat /etc/resolv.conf | grep nameserver，即可查找 Windows IP。

可用工具

工具	描述
list_notebooks	获取完整的笔记本层级结构
search_notes	按查询字符串搜索笔记
read_notebook	阅读指定笔记本的内容
read_note	阅读指定笔记的完整内容
read_multinote	一次阅读多篇笔记
create_note	创建新笔记
create_folder	创建新笔记本
edit_note	编辑现有笔记
edit_folder	编辑现有笔记本
delete_note	删除笔记（需要确认）
delete_folder	删除笔记本（需要确认）
sync	触发同步（默认每 5 分钟自动同步）

开发

pnpm install          # Install dependencies
pnpm build            # Build to dist/
pnpm test             # Run tests
pnpm validate         # Format + lint + typecheck + test + build
pnpm serve:dev        # Dev mode with hot reload (stdio)
pnpm serve:dev:http   # Dev mode with hot reload (HTTP)
pnpm inspect          # Build and open MCP Inspector

许可证

MIT