星战科技xingzhan.cloud
返回市场
乔普林-mcp

乔普林-mcp

作者：alondmnt44 星标更新：2025-11-21
安装使用来源：spider==github.com

项目介绍

Joplin MCP Server

一个基于FastMCP的模型上下文协议（MCP）服务器，用于Joplin笔记应用程序，通过其Python API joppy，使AI助手能够通过标准化接口与您的Joplin笔记、笔记本和标签进行交互。

<!-- mcp-name: io.github.alondmnt/joplin-mcp -->

目录

您可以做什么

此MCP服务器提供了22个优化工具，以实现全面的Joplin集成：

笔记管理

  • 查找与搜索：find_notes，find_notes_with_tag，find_notes_in_notebook，get_all_notes
  • CRUD操作：get_note，get_links，create_note，update_note，delete_note

笔记本管理

  • 组织：list_notebooks，create_notebook，update_notebook，delete_notebook

标签管理

  • 分类：list_tags，create_tag，update_tag，delete_tag，get_tags_by_note
  • 链接：tag_note，untag_note

导入

  • 文件导入：import_from_file - 导入Markdown、HTML、CSV、TXT、JEX文件和目录

    注意：默认情况下禁用导入工具以确保安全。在您的配置中启用 "import_from_file": true。

系统

  • 健康检查：ping_joplin

快速开始

1. 配置Joplin

  1. 打开Joplin桌面版 → 工具 → 选项 → 网络剪辑器
  2. 启用网络剪辑器服务
  3. 复制授权令牌

2. 选择您的AI客户端

选项A：Claude Desktop（在线，商业，自动设置）

运行自动化安装程序：

# 自动安装和配置一切（pip）
pip install joplin-mcp
joplin-mcp-install

# 或使用零安装（推荐如果您有uv）
uvx --from joplin-mcp joplin-mcp-install

# 可选：指定特定版本/范围以保证稳定性
uvx --from joplin-mcp==0.4.1 joplin-mcp-install
uvx --from 'joplin-mcp>=0.4,<0.5' joplin-mcp-install

此脚本将：

  • 配置您的Joplin API令牌
  • 设置工具权限（创建/更新/删除）
  • 自动设置Claude Desktop
  • 测试连接

设置完成后，重新启动Claude Desktop即可！

"列出我的笔记本"或"创建关于今天会议的笔记"

选项B：Jan AI（本地AI模型）

  1. 从https://jan.ai 安装Jan AI

  2. 在Jan的界面中添加MCP服务器：

    • 打开Jan AI
    • 前往设置 → 扩展 → 模型上下文协议
    • 点击添加MCP服务器
    • 配置：
      • 名称：joplin
      • 命令：uvx --from joplin-mcp joplin-mcp-server (需要安装uv)
      • 环境变量：
        • JOPLIN_TOKEN：your_joplin_api_token_here
    • 启用服务器

  3. 开始与您的Joplin笔记进行聊天！

B2：自动化设置（替代方案）

# 如果已经安装了Jan AI，自动安装和配置
pip install joplin-mcp
joplin-mcp-install

这将自动检测并配置Jan AI，就像Claude Desktop一样。

"显示我最近的笔记"或"创建项目规划笔记"

选项C：OllMCP（本地AI模型）

对于本地Ollama模型：

选项C1：自动发现（如果先设置了Claude Desktop）

# 安装ollmcp
pip install ollmcp

# 使用自动发现运行（需要已存在的Claude Desktop配置）
ollmcp --auto-discovery --model qwen3:4b

选项C2：手动设置（独立工作）

# 安装ollmcp
pip install ollmcp

# 设置环境变量
export JOPLIN_TOKEN="your_joplin_api_token_here"

# 使用手动服务器配置运行（需要安装uv）
ollmcp --server "joplin:uvx --from joplin-mcp joplin-mcp-server" --model qwen3:4b

示例用法

配置完成后，您可以向您的AI助手询问：

  • “列出我的所有笔记本” - 查看您的Joplin组织
  • “查找有关Python编程的笔记” - 搜索您的知识库
  • “为今天的站会创建会议笔记” - 快速创建笔记
  • “将我最近的AI笔记标记为‘重要’” - 使用标签进行整理
  • “显示我的待办事项” - 使用find_notes(task=True)查找任务项

工具权限

设置脚本提供3个安全级别：

  • 读取（始终启用）：浏览和搜索您的笔记是安全的
  • 写入（可选）：创建新的笔记、笔记本和标签
  • 更新（可选）：修改现有内容
  • 删除（可选）：永久移除内容

选择与您的舒适度和使用场景相匹配的级别。

高级配置

替代安装方法

方法1：传统的pip安装

如果您没有uvx或希望自定义MCP设置：

# 安装包
pip install joplin-mcp

# 运行设置脚本
joplin-mcp-install

这种方法提供了与uvx joplin-mcp-install相同的功能，但需要本地Python环境。

方法2：开发安装

对于开发者或希望获得最新功能的用户：

macOS/Linux:

git clone https://github.com/alondmnt/joplin-mcp.git
cd joplin-mcp
./install.sh

Windows:

git clone https://github.com/alondmnt/joplin-mcp.git
cd joplin-mcp
install.bat

手动配置

如果您偏好手动设置或脚本无法正常工作：

关于uvx：uvx可以在不永久安装的情况下运行Python应用程序（需要uv：pip install uv）。它可以读写用户配置文件（例如Claude/Jan配置），因此uvx --from joplin-mcp joplin-mcp-install的工作方式类似于pip安装。

版本锁定（可选）：对于长期使用的客户端配置或CI，您可以通过锁定或范围约束版本来保证可重复性，例如uvx --from joplin-mcp==0.4.1 joplin-mcp-install或uvx --from 'joplin-mcp>=0.4,<0.5' joplin-mcp-install。

1. 创建配置文件

在您的项目目录中创建joplin-mcp.json：

{
  "token": "your_api_token_here",
  "host": "localhost", 
  "port": 41184,
  "timeout": 30,
  "verify_ssl": false
}

2. Claude Desktop配置

添加到您的claude_desktop_config.json：

选项A：使用uvx（零安装）

{
  "mcpServers": {
    "joplin": {
      "command": "uvx",
      "args": ["--from", "joplin-mcp", "joplin-mcp-server"],
      "env": {
        "JOPLIN_TOKEN": "your_token_here"
      }
    }
  }
}

需要安装uv：pip install uv

选项B：使用已安装的包

{
  "mcpServers": {
    "joplin": {
      "command": "joplin-mcp-server",
      "env": {
        "JOPLIN_TOKEN": "your_token_here"
      }
    }
  }
}

3. OllMCP手动配置

选项A：使用uvx（零安装）

# 设置环境变量
export JOPLIN_TOKEN="your_token_here"

# 使用手动服务器配置运行
ollmcp --server "joplin:uvx --from joplin-mcp joplin-mcp-server" --model qwen3:4b

需要安装uv：pip install uv

选项B：使用已安装的包

# 设置环境变量
export JOPLIN_TOKEN="your_token_here"

# 使用手动服务器配置运行
ollmcp --server "joplin:joplin-mcp-server" --model qwen3:4b

4. 更多客户端配置示例

包括不同的传输选项（HTTP、SSE、流式HTTP），请参见client-config.json.example。

此文件包括以下配置：

  • STDIO传输（默认，最兼容）
  • HTTP传输（基本HTTP服务器模式）
  • SSE传输（推荐用于gemini-cli和OpenAI客户端）
  • 流式HTTP传输（高级web客户端）
  • HTTP兼容传输（现代/mcp JSON-RPC与遗留/sse//messages客户端之间的桥梁）

工具权限配置

通过编辑您的配置来微调AI可以执行的操作：

{
  "tools": {
    "create_note": true,
    "update_note": true, 
    "delete_note": false,
    "create_notebook": true,
    "delete_notebook": false,
    "create_tag": true,
    "update_tag": false,
    "delete_tag": false,
    "import_from_file": true,
    "get_all_notes": false,
    "update_notebook": false,
    "update_tag": false
  }
}

环境变量

作为JSON配置的替代方案：

export JOPLIN_TOKEN="your_api_token_here"
export JOPLIN_HOST="localhost"
export JOPLIN_PORT="41184"
export JOPLIN_TIMEOUT="30"

HTTP传输支持

服务器支持STDIO和HTTP传输：

# STDIO（默认）
joplin-mcp-server --config ~/.joplin-mcp.json

# HTTP传输（开发，从仓库）
PYTHONPATH=src python -m joplin_mcp.server --transport http --port 8000 --config ./joplin-mcp.json

# 选择加入HTTP兼容捆绑包（现代+遗留SSE端点）
PYTHONPATH=src python -m joplin_mcp.server --transport http-compat --port  8000 --config ./joplin-mcp.json
# 或保持--transport http 并导出 MCP_HTTP_COMPAT=1/true 来切换相同的行为。

HTTP客户端配置

注意：Claude Desktop目前使用STDIO传输，并不直接消费HTTP/SSE配置。以下示例适用于支持网络传输的客户端。

{
  "mcpServers": {
    "joplin": {
      "transport": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

配置参考

基本设置

选项默认值描述
token必需Joplin API认证令牌
hostlocalhostJoplin服务器主机名
port41184Joplin Web剪辑器端口
timeout30请求超时时间（秒）
verify_sslfalseSSL证书验证

工具权限

选项默认值描述
tools.create_notetrue允许创建新笔记
tools.update_notetrue允许修改现有笔记
tools.delete_notetrue允许删除笔记
tools.create_notebooktrue允许创建新笔记本
tools.update_notebookfalse允许修改笔记本标题
tools.delete_notebooktrue允许删除笔记本
tools.create_tagtrue允许创建新标签
tools.update_tagfalse允许修改标签标题
tools.delete_tagtrue允许删除标签
tools.tag_notetrue允许给笔记添加标签
tools.untag_notetrue允许从笔记中移除标签
tools.find_notestrue允许在笔记中进行全文搜索（支持任务过滤）
tools.find_notes_with_tagtrue允许按标签查找笔记（支持任务过滤）
tools.find_notes_in_notebooktrue允许按笔记本查找笔记（支持任务过滤）
tools.get_all_notesfalse允许获取所有笔记（默认禁用 - 可能填充上下文窗口）
tools.get_notetrue允许获取特定笔记
tools.list_notebookstrue允许列出所有笔记本
tools.list_tagstrue允许列出所有标签
tools.get_tags_by_notetrue允许获取特定笔记的标签
tools.ping_joplintrue允许测试服务器连通性
tools.import_from_filefalse允许导入文件/目录（MD、HTML、CSV、TXT、JEX）

内容暴露（隐私设置）

选项默认值描述
content_exposure.search_results"preview"搜索结果中的内容可见性："none"，"preview"，"full"
content_exposure.individual_notes"full"单个笔记的内容可见性："none"，"preview"，"full"
content_exposure.listings"none"笔记列表中的内容可见性："none"，"preview"，"full"
content_exposure.max_preview_length300内容预览的最大长度（字符）

Docker

在容器中运行MCP服务器。默认传输为HTTP，以实现广泛的兼容性；通过环境变量切换传输方式。

构建

docker build -t joplin-mcp .

运行（默认HTTP）

docker run --rm \
  -p 8000:8000 \
  -e JOPLIN_TOKEN=your_api_token \
  joplin-mcp

使用挂载的配置

docker run --rm \
  -p 8000:8000 \
  -v $PWD/joplin-mcp.json:/config/joplin-mcp.json:ro \
  joplin-mcp

选择传输方式

  • SSE（流式）：-e MCP_TRANSPORT=sse
  • 流式HTTP：-e MCP_TRANSPORT=streamable-http
  • STDIO（无端口）：-e MCP_TRANSPORT=stdio

示例（SSE）：

docker run --rm \
  -p 8000:8000 \
  -e JOPLIN_TOKEN=your_api_token \
  -e MCP_TRANSPORT=sse \
  joplin-mcp

容器默认监听0.0.0.0:8000。如果公开暴露，请放置在反向代理后面并在那里终止TLS。对于SSE，请确保代理保持活动状态并适当配置缓冲。

项目结构

  • src/joplin_mcp/ - 主包目录
    • fastmcp_server.py - 包含22个工具和Pydantic验证类型的服务器实现
    • config.py - 配置管理
    • server.py - 服务器入口点（模块和CLI）
    • ui_integration.py - UI集成实用工具
  • docs/ - 文档（故障排除、隐私控制、增强提案）
  • tests/ - 测试套件

测试

测试您的连接：

# 对于pip安装
joplin-mcp-server --config ~/.joplin-mcp.json

# 对于开发（从仓库）
PYTHONPATH=src python -m joplin_mcp.server --config ./joplin-mcp.json

您应该看到：

正在启动Joplin FastMCP服务器...
成功连接到Joplin！
找到X个笔记本，Y个笔记，Z个标签
FastMCP服务器正在启动...
可用工具：22个工具准备就绪

完整的工具参考

工具权限描述
查找笔记
find_notes读取在所有笔记中进行全文搜索（支持任务过滤）
find_notes_with_tag读取