Joplin MCP for Claude & ChatGPT

io.github.kogeler由 GitHub 帳號 kogeler 發布v1.8.1更新於 Nov 15, 2026

Self-hosted Joplin MCP server with built-in OAuth for hosted Claude and ChatGPT Actions

發布方自己的服務:Claude Platform Docs

概覽

AI 產生的概覽

自架式的 Joplin MCP 伺服器,讓助理在你自己的 Joplin 知識庫中搜尋、讀取、建立、更新、加上標籤與刪除筆記。

可以做什麼
  • 搜尋、讀取、建立、更新、移動、加上標籤與刪除筆記和筆記本
  • 上傳、下載、取代附件並追蹤附件關聯
  • 透過本機 stdio 或 Streamable HTTP 提供結構化 MCP 工具
  • 為託管版 Claude 提供內建 GitHub OAuth,並為 ChatGPT 提供需驗證的 Actions
  • 把筆記本拉取成 Markdown 檔案,檢視三方差異與試跑後再推回
  • 以無 root 的 systemd 服務部署無介面 Joplin Terminal 與定期同步
適用情境
適用於助理執行在別處(例如託管版 Claude 或 ChatGPT)、Joplin 以無介面方式執行在伺服器上,或需要處理附件並透過差異與 Git 歷史審閱 Markdown 變更的情境。
執行需求
需要啟用 Web Clipper/Data API 的本機 Joplin(預設埠 41184),或無介面 Joplin Terminal 部署。需要 Joplin Web Clipper 權杖,透過 JOPLIN_TOKEN 或受保護的權杖檔案提供。需要 Python 3.13+ 或原生執行檔;無介面安裝程式需要具備 systemd 使用者服務的 Linux 以及 Node.js/npm。託管存取需要公開的 HTTPS 主機名稱,Claude OAuth 另需 GitHub OAuth App 的 Client ID、Client Secret 與數字使用者 ID。
安裝前請注意
JOPLIN_TOKEN 可存取你的筆記,應放在受保護的檔案或環境變數中;舊的 --token 參數會把權杖暴露在行程清單與 IDE 設定裡。建立、更新、移動、加上標籤與刪除操作會寫入筆記;資源與標籤刪除被明確標示為破壞性操作,因為 Joplin 對它們沒有垃圾桶端點。對外公開轉接器需要 TLS 與獨立 bearer 權杖,Joplin Data API 應留在回環位址。託管 Claude 與 ChatGPT 路由會把筆記資料傳送給這些服務。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Joplin MCP for Claude & ChatGPT,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

Joplin MCP for Claude and ChatGPT

joplin-md-sync gives AI assistants controlled access to your own Joplin knowledge base. Search, read, create, update, move, tag, and trash notes from hosted Claude with a GitHub login, a private Custom GPT, or any local stdio or Streamable HTTP MCP client without moving your notes into another hosted note service.

  • Built-in OAuth for hosted Claude. Claude on claude.ai connects straight to Joplin on your own server through your GitHub login. OAuth is part of the server itself, so there is no separate OAuth proxy or gateway to deploy and configure, and the Joplin Data API stays on loopback.
  • ChatGPT today. A private Custom GPT works through authenticated Actions. OpenAI retires Custom GPTs on 2026-12-11; a ChatGPT MCP connector through the same built-in OAuth is planned as the replacement.
  • One installer for the whole stack. A single command sets up headless Joplin Terminal, recurrent sync, MCP, Actions, and Claude OAuth as rootless systemd services. It asks for the values it needs, hides secrets, generates keys and tokens, and verifies the result.

Run it beside Joplin Desktop, or deploy the complete headless stack on your own Linux host. A separate Markdown sync workflow is available when a coding agent needs reviewable files, three-way diffs, and Git history.

Website · Connect Claude · Connect ChatGPT · MCP: local stdio & HTTP · Deploy headless

What you get

  • Claude with GitHub sign-in. The built-in /oauth/mcp interface lets hosted Claude, currently its only supported OAuth client, sign in with one configured numeric GitHub account on the existing service port. The installer configures it from a few answers; CLI flags and private secret-file options do the same by hand.
  • Joplin inside ChatGPT. A generated OpenAPI contract exposes authenticated Actions for current notes, notebooks, tags, and search to a private Custom GPT.
  • Typed MCP tools. Local stdio and Streamable HTTP transports give compatible clients structured note operations plus attachment upload, download, replacement, and relationship traversal.
  • A headless Joplin service. The rootless Linux installer deploys Joplin Terminal, recurrent sync, and the combined MCP, OAuth, and Actions adapter as coordinated systemd user services. Joplin Desktop does not need to remain running.
  • Your storage and encryption choices. Use filesystem, Nextcloud, WebDAV, Dropbox, OneDrive, S3, Joplin Server, or Joplin Cloud, with existing Joplin end-to-end encryption where the selected topology supports it.
  • Reviewable Markdown when you need it. Pull notebooks to ordinary files, let an agent work with repository context, inspect a three-way diff and dry-run, then push the verified result back to Joplin.

Joplin remains the source of truth. The adapter uses its documented local Data API and never edits the Joplin database, profile, or sync target directly.

Joplin Desktop also ships its own MCP server for clients on the same computer. Use this project when the assistant runs elsewhere, such as hosted Claude or ChatGPT, when Joplin runs headless on a server, or when you need attachments and reviewable Markdown changes. See the comparison.

Fast path: headless Joplin for Claude and ChatGPT

This topology keeps Joplin and the adapter on your own Linux host. Only the authenticated OAuth or Actions routes need to reach the assistant over HTTPS; the Joplin Data API stays on loopback.

1. Install Joplin and the agent service

The host needs Linux with systemd user services, Python 3.13.5 or newer, and Node.js/npm. This interactive example connects the new headless profile to an existing Nextcloud Joplin sync target:

bash
set -o pipefailcurl --proto '=https' --tlsv1.2 --fail --silent --show-error --location \  'https://raw.githubusercontent.com/kogeler/joplin-md-sync/main/scripts/joplin_terminal_service/install_joplin_terminal.py' \  | python3 - \      --sync-target nextcloud \      --sync-location 'https://cloud.example.com/remote.php/dav/files/user/Joplin' \      --sync-username 'user'

The installer asks for secrets through hidden prompts, offers GitHub OAuth for Claude, handles existing Joplin E2EE keys, verifies release checksums, and creates:

text
joplin-terminal.service    Joplin profile, Data API, and recurrent syncjoplin-md-sync.service     MCP, Claude OAuth, and ChatGPT Actions on one guarded adapter

It also generates separate protected credentials for Joplin, MCP, and Actions, plus the OAuth signing key when OAuth is enabled. For ready-to-run Nextcloud, custom S3, and uninstall commands, see Joplin Headless Service. The guide also explains installed paths, every installer option, and upgrades.

2. Publish the narrow HTTPS routes

From a trusted HTTPS hostname, route only what your assistant needs to the adapter on 127.0.0.1:8765: the OAuth routes for Claude, /api/gpt/v1/* for ChatGPT, or both. Do not expose the upstream Joplin Data API. Keep /mcp private unless a remote MCP client needs it; public MCP requires its own bearer token and TLS.

The supported boundaries and deployment choices are documented in Self-hosted deployment.

3. Connect Claude

Register a GitHub OAuth App, then answer yes to the installer's Enable GitHub OAuth for Claude? question or rerun it with --github-oauth. It asks for the public HTTPS origin, the app's Client ID and Client Secret, and your numeric GitHub user ID, then enables OAuth on the running service and checks it. Add https://YOUR_HOST/oauth/mcp as a custom connector in Claude and sign in with GitHub. The exact routes, app settings, and checks are in the Claude connector guide.

4. Connect a private Custom GPT

From a checkout matching the deployed release, run the setup assistant:

bash
git clone --depth 1 --branch v1.8.1 \  https://github.com/kogeler/joplin-md-sync.gitcd joplin-md-syncpython3 scripts/prepare_chatgpt_action.py

Enter the public hostname and the generated Actions token when prompted. The assistant validates TLS, authentication, and live read operations, then writes the OpenAPI file for the Custom GPT editor. Continue with the exact GPT instructions and acceptance test in ChatGPT Actions setup.

Use Joplin from an MCP client

For a local Joplin Desktop instance, enable Tools > Options > Web Clipper and point an MCP-capable editor at the downloaded native executable:

json
{  "mcpServers": {    "joplin": {      "command": "/absolute/path/to/joplin-md-sync-linux-amd64",      "args": ["mcp", "stdio", "--token-file", "/home/USER/.config/joplin-md-sync/token"]    }  }}

Store the token once in a private file outside synchronized folders. The directory is 0700, the file 0600, and the token is read without echo or shell history:

bash
install -d -m 0700 ~/.config/joplin-md-sync(umask 077; read -rs -p 'Joplin token: ' token &&  printf '%s\n' "$token" > ~/.config/joplin-md-sync/token)

A launcher that exports environment variables can set JOPLIN_TOKEN instead and pass neither token option. Use exactly one source: a command-line option together with a non-empty JOPLIN_TOKEN is rejected. The older "--token", "<token>" arguments still work for existing configurations, but they place the token in the IDE configuration, in the process list, and in any agent command line that forwards the MCP configuration.

The local stdio process connects to Joplin on port 41184 by default; add "--port", "PORT" to the arguments when Joplin uses another local port. For a long-running or remote adapter, install the package and start Streamable HTTP instead. Stdio opens no MCP or Actions port and therefore needs no bearer token for those interfaces; its Joplin token authenticates only to Joplin:

bash
pipx install "joplin-md-sync==1.8.1"export JOPLIN_TOKEN=...joplin-md-sync mcp serve

Connect the HTTP client to http://127.0.0.1:8765/mcp with transport type streamable-http.

The service can start while Joplin is offline and recovers on later calls. Create operations reject an existing notebook, note, tag, or resource identity instead of creating accidental duplicates. Remote MCP deployment requires a separate protected bearer token and TLS. See the complete MCP API reference.

Use Joplin notes as reviewable files

Choose the Markdown workflow when an agent needs repository context, broad transformations, an exact diff before writes, or selected notebooks in Git:

bash
export JOPLIN_TOKEN=...joplin-md-sync init --root ./notes --mode remote-firstjoplin-md-sync pull --root ./notes --json
# Let an agent edit the managed Markdown files, then review the result.joplin-md-sync diff --root ./notes --three-way --unifiedjoplin-md-sync push --root ./notes --dry-run --jsonjoplin-md-sync push --root ./notes --json

Managed note files carry a one-line Joplin identity header. Base snapshots, conflicts, journals, backups, and downloaded resources stay under the ignored .joplin-sync/ directory. Start with the copyable agent notes repository template or the Markdown quick start.

Control and failure behavior

  • The Joplin Data API remains private on loopback in the headless topology.
  • Joplin, MCP, and Actions credentials are distinct and read from protected files or the environment. Local mcp stdio takes its Joplin token from a protected --token-file or JOPLIN_TOKEN; the compatibility --token argument exposes it in the process list.
  • Direct API writes are sent once. An ambiguous timeout is reported instead of being replayed and possibly duplicated.
  • Creating an occupied notebook, note, tag, or resource identity returns an explicit *_ALREADY_EXISTS error with the existing ID and recommended update tool.
  • Note and notebook deletion uses Joplin trash. Resource and tag deletion is explicitly marked destructive because Joplin has no trash endpoint for them.
  • Divergent file edits produce a conflict bundle instead of a silent overwrite.
  • File deletion propagation is off by default; interrupted mutations are journaled and recoverable; diff never mutates state.

The exact test-backed guarantees live in the contract catalog. Agents operating a Markdown workspace should also follow AGENTS.md.

Installation options

Python installations require CPython 3.13 or 3.14 on Windows or Linux:

bash
python -m pip install "joplin-md-sync==1.8.1"# or: pipx install "joplin-md-sync==1.8.1"

Native executables from GitHub Releases include Python and the standard service runtime. A Python zipapp is also available for a prepared Python environment:

PlatformAsset
Linux AMD64joplin-md-sync-linux-amd64
Linux ARM64joplin-md-sync-linux-arm64
Windows AMD64joplin-md-sync-windows-amd64.exe
Python zipappjoplin-md-sync.pyz

Download them with SHA256SUMS.txt from the latest release.

Interface guide

GoalInterface
Connect hosted Claude with GitHub sign-inBuilt-in OAuth MCP at /oauth/mcp
Work with current Joplin notes in ChatGPTAuthenticated ChatGPT Actions
Give an editor or assistant typed note toolsMCP
Run without a desktop sessionHeadless Joplin Terminal plus MCP, OAuth, or Actions
Review every broad agent edit before applying itMarkdown workspace
Keep selected notebooks in GitMarkdown workspace

Compare consistency models and deployment choices in Choose an agent interface.

Development

bash
make venvmake venv-devmake checkmake cimake test-livemake packagemake docs-auditmake docs-screenshotsmake help

The standard installation includes the HTTP and GitHub OAuth runtime; CLI flags enable the interfaces. Development, test, package, and docs tools use separate dependency groups from the single hash-verified uv.lock. See Development and Dependency maintenance. On Linux AMD64, make test-live provisions a checksum-pinned Joplin Desktop 3.6.15 binary and isolated temporary profile; it never uses the user's Joplin process or token.

Releases and license

Git tags use vX.Y.Z. Release assets include wheel, sdist, zipapp, native executables, and checksums; the same wheel and sdist are published to PyPI through Trusted Publishing. See the changelog.

MIT licensed. This is an independent project and is not affiliated with or endorsed by the Joplin project.

來源:README.md,提交 80d501e

工具

0
SourceWeft 曾在隔離沙箱中以無憑證方式啟動該軟體包一次,以列出其工具,但未能完成:軟體包安裝失敗。

版本歷史

1
  1. v1.8.1最新Nov 15, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分

其他 Claude 整合