MCP Joplin サーバー

Joplinノートと統合するModel Context Protocol (MCP) サーバーです。AIクライアント（Perplexityなど）がJoplinのWeb Clipper APIを通じてノートブックやノートにアクセスし、操作できるようにします。

機能

🔍 検索機能: ノートやノートブックを検索
📖 コンテンツ読み取り: 特定のノートの完全なコンテンツを取得
📝 作成機能: 新しいノートやノートブックを作成
✏️ 更新/編集機能: ノートのコンテンツ更新、ノートへの追記、ノートブック名の変更
🗑️ 削除機能: ノートやノートブックを削除（ゴミ箱への移動または完全削除をサポート）
🔄 移動機能: ノートを別のノートブックへ移動
📋 リスト機能: すべてのノートブック、および特定のノートブック内のノートをリスト表示

要件

Joplin Desktop - インストールされ、実行されていること
Node.js 18+ - MCPサーバーの実行に必要
Web Clipperの有効化 - JoplinでWeb Clipperサービスを有効にすること

インストールとセットアップ

1. Joplin Web Clipperを有効にする

Joplinデスクトップアプリケーションを開く
ツール → オプション → Web Clipper に移動
Web Clipperサービスを有効にする にチェックを入れる
表示されている ポート番号 を確認する（通常は41184）
APIトークンをコピーする（認証が必要な場合）

2. MCP Joplin サーバーをインストールする

# Clone or download this project
cd mcp-joplin

# Install dependencies
npm install

# Compile TypeScript
npm run build

3. テスト実行

# Run directly (will auto-detect Joplin service)
npm start

# Or specify port
npm start -- --port 41184

# Or specify token (if needed)
npm start -- --token YOUR_API_TOKEN

# View help
npm start -- --help

4. npxを使用する場合

# Global installation (recommended)
npm install -g .

# Then use anywhere
npx mcp-joplin

# Or run locally
npx . --port 41184

MCPクライアントの設定

Perplexityやその他のMCPクライアントの設定

MCPクライアントの設定ファイルに以下の設定を追加してください：

🔐 設定（APIトークンが必要）

このMCPサーバーが正しく機能するには、Joplin APIトークンが必要です：

{
  "mcpServers": {
    "joplin": {
      "command": "npx",
      "args": [
        "/ABSOLUTE/PATH/TO/mcp-joplin",
        "--port",
        "41184",
        "--token",
        "YOUR_API_TOKEN"
      ]
    }
  }
}

💡 重要: このMCPサーバーが正しく動作するためにはAPIトークンが必要です。

Claude Desktopの設定例

Claude Desktopの設定

~/Library/Application Support/Claude/claude_desktop_config.json に以下を記述します：

{
  "mcpServers": {
    "joplin": {
      "command": "npx",
      "args": [
        "/Users/yourusername/path/to/mcp-joplin",
        "--token",
        "YOUR_API_TOKEN"
      ]
    }
  }
}

利用可能なMCPツール

1. get_note_content

特定のノートの完全なコンテンツを取得します

Parameters: noteId (string) - The ID of the note

2. search_notes

ノートを検索します

Parameters:
- query (string) - Search keywords
- limit (number, optional) - Result limit (default: 20)

3. search_notebooks

ノートブックを検索します

Parameters: query (string) - Search keywords

4. list_notebooks

すべてのノートブックをリスト表示します

Parameters: None

5. list_notes

特定のノートブック内のノートをリスト表示します

Parameters:
- notebookId (string) - The ID of the notebook
- limit (number, optional) - Result limit (default: 50)

5.1. list_sub_notebooks

特定のノートブック内のサブノートブックをリスト表示します

Parameters:
- parentNotebookId (string) - The ID of the parent notebook

6. create_note

新しいノートを作成します

Parameters:
- title (string) - Note title
- body (string) - Note content (Markdown format)
- notebookId (string, optional) - Target notebook ID

7. create_notebook

新しいノートブックを作成します

Parameters:
- title (string) - Notebook title
- parentId (string, optional) - Parent notebook ID (for sub-notebooks)

8. delete_note

ノートを削除します

Parameters:
- noteId (string) - ID of the note to delete
- permanent (boolean, optional) - Whether to permanently delete (default: false, moves to trash)

9. delete_notebook

ノートブックを削除します

Parameters:
- notebookId (string) - ID of the notebook to delete
- permanent (boolean, optional) - Whether to permanently delete (default: false, moves to trash)

10. move_note

ノートを別のノートブックに移動します

Parameters:
- noteId (string) - ID of the note to move
- targetNotebookId (string) - Target notebook ID

11. update_note

既存のノートのタイトルや本文を更新します

Parameters:
- noteId (string) - ID of the note to update
- title (string, optional) - New note title
- body (string, optional) - New note content (full replacement, not a patch)

注:

title または body の少なくとも一方が必要です
ノートのコンテンツを置き換える場合やノート名を変更する場合に使用してください

12. append_to_note

既存のノートの末尾にコンテンツを追記します

Parameters:
- noteId (string) - ID of the note to append to
- content (string) - Content to append
- separator (string, optional) - Separator inserted before appended content (default: "\n\n")

注:

ログ、会議メモ、補足情報、テスト結果などに使用してください
既存の本文を置き換えずにコンテンツを追加したい場合は、update_note よりもこちらを優先してください

13. update_notebook

既存のノートブック名を更新します

Parameters:
- notebookId (string) - ID of the notebook to update
- title (string) - New notebook title

14. scan_unchecked_items

ノートブックとサブノートブックをスキャンし、未完了のToDoアイテム (- [ ]) を探します

Parameters:
- notebookId (string) - ID of the notebook to scan
- includeSubNotebooks (boolean, optional) - Whether to recursively scan sub-notebooks (default: true)

編集のセマンティクス

ノートのタイトルや本文を置き換えるには update_note を使用します
既存のコンテンツを保持したままノートの末尾にコンテンツを追加するには append_to_note を使用します
ノートが属するノートブックを変更するには move_note を使用します
ノートブックの名前を変更するには update_notebook を使用します

使用例

AIクライアントでの会話例:

You: "Search for notes containing 'Python'"
AI: Using search_notes tool to search for relevant notes...

You: "Create a new notebook called 'Learning Plan'"
AI: Using create_notebook tool to create a new notebook...

You: "Create a note about JavaScript in the Learning Plan notebook"
AI: Using list_notebooks to find the notebook ID, then using create_note to create the note...

You: "Show the complete content of a specific note"
AI: Using get_note_content tool to retrieve note content...

You: "Update the title of note abc123 to Weekly Review"
AI: Using update_note tool to rename the note...

You: "Append these test results to note abc123"
AI: Using append_to_note tool to add the new content to the end of the note...

You: "Rename notebook xyz789 to Project Archive"
AI: Using update_notebook tool to rename the notebook...

You: "Scan my project notebook for all uncompleted todo items"
AI: Using scan_unchecked_items tool to scan all sub-notebooks...

トラブルシューティング

接続の問題

Joplinが実行中であることを確認
- Joplinデスクトップアプリケーションを開いたままにする必要があります
Web Clipperの設定を確認
- Web Clipperサービスが有効になっていることを確認してください
- ポート設定を確認してください（デフォルトは41184）

エラーメッセージを確認

# Use verbose mode to see errors
DEBUG=* npm start

よくあるエラー

"Joplin Web Clipper service not found": Joplinが実行中であり、Web Clipperが有効であることを確認してください
"Connection refused": ポート設定が正しいか確認してください
"Unauthorized" または "403 Forbidden": APIトークンが必要です（以下の手順を参照）

🔑 APIトークンが必要

このMCPサーバーが正しく機能するにはAPIトークンが必要です。

APIトークンの取得方法

Joplinで ツール → オプション → Web Clipper に移動
表示されている トークン をコピー
起動コマンドに --token YOUR_TOKEN を追加

開発

# Run in development mode
npm run dev

# Compile
npm run build

# Prepare for publishing
npm run prepublishOnly

技術アーキテクチャ

言語: TypeScript/Node.js
MCP SDK: @modelcontextprotocol/sdk
HTTPクライアント: axios
CLI: commander
API: Joplin Web Clipper API

技術的な詳細

ノートブック検索: Joplinの検索APIにはフォルダ検索の制限があるため、クライアントサイドでのフィルタリングを使用してノートブック検索機能を実装しています
ページネーション処理: Joplin APIのページネーションメカニズム（デフォルトで1ページあたり100アイテム）を自動的に処理し、ノートブックとノートのリストを完全に取り出せるようにしています。これにより、サブノートブックが不完全になる問題を解決しています
エラーハンドリング: Joplin APIエラーやネットワーク接続エラーを含む、完全なエラーハンドリングメカニズムを備えています
自動検出: Joplin Web Clipperのポート（41184-41194）の自動検出をサポートしています

ライセンス

MITライセンス

コントリビューション

Issueやプルリクエストを歓迎します！

サポート

問題が発生した場合は、以下を確認してください:

Joplin Web Clipperが正常に動作しているか確認
エラーメッセージとログを確認
詳細なエラー情報を添えてIssueを提出