Joplin MCP Server

🚀 Joplin MCP 服務器

這是一個為 Joplin 實現的基於 Node.js 的 MCP（模型上下文協議）服務器。

🚀 快速開始

本項目是一個用於 Joplin 的 MCP 服務器的 Node.js 實現。你可以按照以下步驟快速開始使用該服務器。

✨ 主要特性

• 支持本地開發和使用 npx 運行，方便快捷。
• 提供多種命令行選項，可靈活配置服務器。
• 支持多種操作，如獲取筆記本層級結構、搜索筆記、讀取筆記本和筆記內容等。

📦 安裝指南

在項目根目錄下執行以下命令安裝依賴：

npm install

💻 使用示例

基礎用法

本地開發

啟動服務器：

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"
    ]
  }
}

日誌記錄

服務器會記錄所有傳入的命令和傳出的響應。日誌存儲在兩個位置：

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

💡 使用建議

當你搜索筆記或查看筆記本時，會看到使用 read_multinote 和找到的筆記的確切 ID 的建議。這使得一次讀取多個相關筆記變得容易。

📚 詳細文檔

開發

本地開發設置

在開發期間本地測試 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 鏈接，更改立即可用。

運行測試

創建一個包含測試配置的 .env.test.local 文件，然後運行：

npm test

發佈到 npm

要使此包可通過 npx 使用：

1. 在 package.json 中更新版本。
2. 運行 npm publish。 用戶隨後可以使用 npx joplin-mcp-server 運行它。

取消鏈接（如果需要）

要移除本地鏈接：

npm unlink -g joplin-mcp-server

📄 許可證

MIT 許可證