Joplin MCP Server

🚀 Joplin MCP Server

このプロジェクトは、Joplin用のMCP（Model Context Protocol）サーバーをNode.jsで実装したものです。Joplinとの連携を通じて、ノートやノートブックの操作を容易に行うことができます。

🚀 クイックスタート

このサーバーを使用することで、Joplinのノートやノートブックを簡単に操作できます。以下の手順に従ってサーバーをセットアップしてください。

✨ 主な機能

• JoplinとのMCPプロトコルによる通信をサポート
• ノートブックの一覧取得、ノートの検索、読み取りなどの操作が可能
• 複数のノートを一度に読み取る機能も搭載

📦 インストール

プロジェクトをインストールするには、以下のコマンドを実行します。

npm install

📚 ドキュメント

設定

.envファイルを作成し、以下の変数を設定してください。

JOPLIN_PORT=41184
JOPLIN_TOKEN=your_joplin_token

Joplinのトークンは、Joplinデスクトップアプリの「ツール > オプション > Webクリッパー」から取得できます。

使用方法

ローカル開発

サーバーを起動するには、以下のコマンドを実行します。

npm start

カスタム環境ファイルを指定することもできます。

npm start -- --env-file .env.custom

npxを使用する（推奨）

npmに公開した後は、npxを使用してサーバーをインストールせずに実行できます。

# コマンドライン引数を使用する
npx joplin-mcp-server --port 41184 --token your_joplin_token

# 環境ファイルを使用する
npx joplin-mcp-server --env-file /path/to/your/.env

# 混合アプローチ（引数が環境ファイルを上書きする）
npx joplin-mcp-server --env-file .env --port 41185

コマンドラインオプション

OPTIONS:
  --env-file <file>    環境変数をファイルから読み込む
  --port <port>        Joplinのポート（デフォルト: 41184）
  --token <token>      JoplinのAPIトークン
  --help, -h           ヘルプメッセージを表示

MCPクライアントの設定

Augment Codeでの使用方法:

name: joplin
command: npx joplin-mcp-server --port 41184 --token your_token

mcp.json（Cursorやその他のツール）での使用方法:

{
  "joplin": {
    "command": "npx",
    "args": ["joplin-mcp-server", "--port", "41184", "--token", "your_joplin_token"]
  }
}

環境ファイルを使用する場合:

{
  "joplin": {
    "command": "npx",
    "args": ["joplin-mcp-server", "--env-file", "/path/to/your/.env"]
  }
}

レガシーな使用方法（ローカルにインストールした場合）

Augment Codeでの使用方法: name: joplin command: node /path/to/your/mcp-joplin/index.js --env-file /path/to/your/mcp-joplin/.env mcp.json（Cursorやその他のツール）での使用方法:

{
  "joplin": {
    "command": "node",
    "args": [
      "/path/to/your/mcp-joplin/index.js",
      "--env-file",
      "/path/to/your/mcp-joplin/.env"
    ]
  }
}

ログ出力

サーバーはすべての入力コマンドと出力レスポンスをログに記録します。ログは以下の2箇所に保存されます。

1. コンソール出力: 基本的な情報がコンソールに表示されます
2. ログファイル: 詳細なログがlogsディレクトリにタイムスタンプ付きで保存されます

LOG_LEVEL環境変数を設定することで、ログレベルを調整できます。

LOG_LEVEL=debug npm start

利用可能なログレベル（詳細度が高い順）:

• debug: 詳細なコマンドとレスポンスデータを含むすべてのメッセージ
• info: 標準的な運用メッセージ（デフォルト）
• warn: 警告とエラーのみ
• error: エラーメッセージのみ

利用可能なツール

list_notebooks

Joplinから完全なノートブック階層を取得します。

# 出力例:
Notebook 1 (id: "abc123")
  Subnotebook 1.1 (id: "def456")
  Subnotebook 1.2 (id: "ghi789")
Notebook 2 (id: "jkl012")

search_notes

Joplin内のノートを検索し、一致するノートブックを返します。 パラメーター:

• query: 検索クエリ文字列

# 使用例:
search_notes query="project meeting"

# 出力例:
Found 2 notes matching query: "project meeting"
NOTE: To read a notebook, use the notebook ID (not the note title)

- Note: "Weekly Project Meeting" (note_id: "abc123")
  Notebook: "Work" (notebook_id: "58a0a29f68bc4141b49c99f5d367638a")
  Updated: 3/15/2025, 10:30:45 AM
  Snippet: Notes from our weekly project meeting. Topics discussed: timeline, resources, next steps...
  To read this notebook: read_notebook notebook_id="58a0a29f68bc4141b49c99f5d367638a"

- Note: "Project Kickoff Meeting" (note_id: "def456")
  Notebook: "Projects" (notebook_id: "72b1c45d89ef3212a67b98f4e5d23a1b")
  Updated: 3/10/2025, 2:15:30 PM
  Snippet: Initial project meeting with stakeholders. Key decisions: project scope, team members...
  To read this notebook: read_notebook notebook_id="72b1c45d89ef3212a67b98f4e5d23a1b"

⚠️ 重要提示

ノートのタイトルとIDの違いに注意してください。read_notebookコマンドを使用する際には、ノートブックのID（長い英数字の文字列）を使用する必要があります。

read_notebook

特定のノートブックの内容を読み取ります。 パラメーター:

• notebook_id: 読み取るノートブックのID

# 使用例:
read_notebook notebook_id="58a0a29f68bc4141b49c99f5d367638a"

# 出力例:
# Notebook: "Work" (notebook_id: "58a0a29f68bc4141b49c99f5d367638a")
Contains 3 notes:
NOTE: This is showing the contents of notebook "Work", not a specific note.

- Note: "Weekly Project Meeting" (note_id: "def456")
  Updated: 3/15/2025, 10:30:45 AM

- ✅ Note: "Call client" (note_id: "ghi789")
  Updated: 3/14/2025, 3:45:12 PM

- ☐ Note: "Prepare presentation" (note_id: "jkl012")
  Updated: 3/13/2025, 9:20:33 AM

⚠️ 重要提示

ノートのタイトル（例: "todo"）ではなく、ノートブックのIDを使用しないとエラーが発生します。常に検索結果やノートブックリストに表示されるノートブックのID（長い英数字の文字列）を使用してください。

read_note

特定のノートの全内容を読み取ります。 パラメーター:

• note_id: 読み取るノートのID

# 使用例:
read_note note_id="def456"

# 出力例:
# Note: "Weekly Project Meeting"
Note ID: def456
Notebook: "Work" (notebook_id: "58a0a29f68bc4141b49c99f5d367638a")
Created: 3/15/2025, 10:00:12 AM
Updated: 3/15/2025, 10:30:45 AM

---

# Weekly Project Meeting

## Agenda
1. Project status update
2. Timeline review
3. Resource allocation
4. Next steps

## Notes
- Project is on track for Q2 delivery
- Need to allocate additional resources to the UI team
- Next meeting scheduled for next Friday

---

Related commands:
- To view the notebook containing this note: read_notebook notebook_id="58a0a29f68bc4141b49c99f5d367638a"
- To search for more notes: search_notes query="your search term"

💡 使用建议

read_noteコマンドは特定のノートの全内容を表示し、read_notebookコマンドはノートブック内のノートのリストを表示します。search_notesを使用してノートを検索し、そのIDを取得してください。

read_multinote

複数のノートの全内容を一度に読み取ります。 パラメーター:

• note_ids: 読み取るノートのIDの配列

# 使用例:
read_multinote note_ids=["def456", "ghi789", "jkl012"]

# 出力例:
# Reading 3 notes

## Note 1 of 3 (ID: def456)

### Note: "Weekly Project Meeting"
Notebook: "Work" (notebook_id: "58a0a29f68bc4141b49c99f5d367638a")
Created: 3/15/2025, 10:00:12 AM
Updated: 3/15/2025, 10:30:45 AM

---

# Weekly Project Meeting

## Agenda
1. Project status update
2. Timeline review

---

## Note 2 of 3 (ID: ghi789)

### Note: "Call client"
Notebook: "Work" (notebook_id: "58a0a29f68bc4141b49c99f5d367638a")
Status: Completed
Created: 3/14/2025, 3:00:00 PM
Updated: 3/14/2025, 3:45:12 PM

---

Discussed project timeline and next steps.
Client is happy with progress.

---

## Note 3 of 3 (ID: jkl012)

### Note: "Prepare presentation"
Notebook: "Work" (notebook_id: "58a0a29f68bc4141b49c99f5d367638a")
Status: Not completed
Due: 3/20/2025, 9:00:00 AM
Created: 3/13/2025, 9:00:00 AM
Updated: 3/13/2025, 9:20:33 AM

---

# Presentation Outline
- Introduction
- Project overview
- Timeline
- Budget
- Next steps

---

# Summary
Total notes requested: 3
Successfully retrieved: 3

💡 使用建议

ノートを検索したりノートブックを表示したときに、見つかったノートの正確なIDを使用してread_multinoteを使う提案が表示されます。これにより、関連する複数のノートを一度に読むことが簡単になります。

開発

ローカル開発環境のセットアップ

開発中にnpxコマンドをローカルでテストするには、以下のコマンドを実行します。

# プロジェクトのルートディレクトリで
cd /path/to/mcp-joplin
npm install
npm link

リンクした後は、ローカルの変更をすぐにテストできます。

# CLIをテストする
npx joplin-mcp-server --help
npx joplin-mcp-server --port 41184 --token your_token

# コードを変更した後、再度テストする（再ビルド不要）
npx joplin-mcp-server --help

変更を加える

1. プロジェクト内の任意の.jsファイルを編集します
2. テストを実行します: npm test
3. CLIをテストします: npx joplin-mcp-server --help

ビルドステップは必要ありません - npm linkを通じて変更がすぐに利用可能になります。

テストの実行

テスト用の設定を含む.env.test.localファイルを作成し、以下のコマンドを実行します。

npm test

npmへの公開

このパッケージをnpxで利用可能にするには、以下の手順を行います。

1. package.jsonのバージョンを更新します
2. npm publishを実行します

ユーザーはnpx joplin-mcp-serverでこのパッケージを実行できます。

リンクの解除（必要な場合）

ローカルのリンクを削除するには、以下のコマンドを実行します。

npm unlink -g joplin-mcp-server

📄 ライセンス

MITライセンスの下で公開されています。