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 许可证