Joplin MCP Server

乔普林MCP服务器

一个自包含的MCP（模型上下文协议）服务器，用于 乔普林。将Joplin终端CLI捆绑为依赖项——无需桌面应用程序，无需全局安装，也无需管理外部进程。通过自动端口协商与Joplin Desktop共存。

快速开始

npx joplin-mcp-server --token your_joplin_token

就是这样。服务器生成自己的Joplin终端实例（sidecar模式），同步到您配置的后端，并通过MCP公开您的笔记。

建筑

侧车模式（默认）

服务器捆绑 joplin 作为npm依赖，并管理自己的Joplin终端进程。不需要Joplin桌面应用程序-sidecar处理一切：数据存储、同步和RESTneneneba 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 user@example.com --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

配置

环境变量

命令行选项

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

路径扩展

这 --sync-path 和 --profile 选项支持 ~ 以及跨平台兼容性的环境变量扩展：

# 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.jsonClaude Desktop），其中没有shell扩展。

WSL自动检测： 在WSL上，如果 ~/ 路径为空或缺失，服务器会自动检查相应的Windows路径 /mnt/c/Users//...这意味着 --sync-path ~/OneDrive/Apps/Joplin 只在WSL上工作，不需要完整的 /mnt/c/... 路径。

同步目标

MCP客户端配置

克劳德代码

存储库包括 .mcp.json 这适用于Claude Code的env-var扩展：

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

集 JOPLIN_TOKEN 在你的shell中（添加到 ~/.bashrc 或 ~/.zshrc):

export JOPLIN_TOKEN="your_actual_token_here"

克劳德桌面

克劳德桌面 不 支持 ${VAR} 扩张。直接提供值：

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

带同步（克劳德桌面）

{
  "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 build -t joplin-mcp .
docker run -e JOPLIN_TOKEN=your_token -p 3000:3000 joplin-mcp

WSL设置

在WSL跑步？sidecar架构使这一点变得简单明了——不需要Windows端口转发。服务器自动检测WSL并处理Linux和Windows文件系统之间的路径解析。

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

您的Windows Joplin桌面和WSL sidecar都同步到同一个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文件夹： 工具>选项>同步>文件系统>/用户/你的名字/OneDrive/应用程序/乔普林

乔普林桌面共存： 如果Desktop在端口41184上运行，sidecar会自动使用下一个可用端口。启动时会记录一条警告，提醒您两个实例使用单独的数据库，需要相同的同步目标才能保持同步。

云同步

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

npx joplin-mcp-server --token your_token \
  --sync-target joplin-cloud \
  --sync-username user@example.com --sync-password pass

外部模式（端口转发）

如果你更喜欢直接连接到Windows Joplin而不是运行sidecar：

在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 IP ipconfig 在Windows或 cat /etc/resolv.conf | grep nameserver 来自WSL。

可用工具

发展

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

许可证

麻省理工学院