Сервер Model Context Protocol (MCP) для приложения Joplin.

Разработанный belsar.ai, он прост в установке и приятен в использовании.

Видео

[[Т0]]

Поддержка платформы

Доступен на macOS и Linux. Пользователи Windows должны использовать WSL2.

Архитектура

По умолчанию этот MCP-сервер предоставляет два инструмента:

• [[Т1]]: Для запуска сценариев в режиме только для чтения (инспектирование / чтение заметок и записных книжек).
• [[Т2]]: Для запуска скриптов, которые также могут выполнять модификации, создания или удаления.

Этот шаблон исполнения на основе сценария следует рекомендуемому шаблону Anthropic для серверов MCP и является наиболее эффективным способом создания MCP-сервера сегодня.

Скрипты выполняются в отдельном процессе запуска, изолированном на уровне ОС Anthropic Sandbox Runtime. node:vm ограничивает глобали, доступные внутри этого процесса; Sandbox Runtime является границей безопасности, которая блокирует доступ к сети и записывает файловую систему.

Бегун называет методы 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