
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
概览
自托管的 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。
安装
在 SourceWeft 中
- 打开 控制台中的 Joplin MCP for Claude & ChatGPT,将其添加到工作区。
- 为需要使用其工具的对话启用该服务。
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/mcpinterface 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:
The installer asks for secrets through hidden prompts, offers GitHub OAuth for Claude, handles existing Joplin E2EE keys, verifies release checksums, and creates:
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:
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:
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:
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:
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:
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 stdiotakes its Joplin token from a protected--token-fileorJOPLIN_TOKEN; the compatibility--tokenargument 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_EXISTSerror 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;
diffnever 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:
Native executables from GitHub Releases include Python and the standard service runtime. A Python zipapp is also available for a prepared Python environment:
Download them with SHA256SUMS.txt from the
latest release.
Interface guide
Compare consistency models and deployment choices in Choose an agent interface.
Development
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版本历史
1- v1.8.1最新Nov 15, 2026
评分
已满足适用检查项的 50%
该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。
- 近 30 天内可连通25 分
请保持端点能够响应 MCP 握手;SourceWeft 每 30 天探测一次。
- 已声明认证方式10 分
请在注册中心条目中声明凭据请求头,或保持端点能够响应探测,以便判定其认证方式。
- 已列出工具15 分
请让服务器在无凭据时响应 tools/list,或发布可在沙箱中无凭据启动的软件包。
- 描述必需15 分
- 图标10 分
- 文档15 分
- 许可证10 分
其他 Claude 集成
Claude Platform Docs
com.claude.platform官方发布者
远程 MCP 服务器,让助手搜索并阅读 Claude 平台文档与 API 参考。

Claude Roslyn Lsp
由 GitHub 账号 lahma 发布
把微软 Roslyn C# 语言服务器接入助手,用于语义符号查找、引用、诊断、代码操作、重命名与格式化。

Claude SEO Skills
由 GitHub 账号 NoteSupreme 发布
一个免费、只读的远程 MCP 服务器,让助手检索并阅读两套开源 SEO 技能包,并按其中的说明执行。

Mcp Claude Usage Guard
由 GitHub 账号 GuardBee 发布
一个 MCP 服务器,通过对比账户套餐用量表与本机记录,判断 Claude 套餐用量是否都来自本机的 Claude Code。

WebDesk for Claude
由 GitHub 账号 Red-Center-Studio 发布
Build and publish small business websites from Claude. Free plan, sign in with an email code.