慕恩-MCP服务器

Name: 慕恩-MCP服务器
Author: z4656207

作者：z465620747 星标更新：2025-06-22

安装使用来源：spider==github.com

项目介绍

技术文档摘要

Mowen Notes MCP Server

这是一个基于模型上下文协议（MCP）的服务器，用于与Mowen笔记软件进行交互。通过此服务器，您可以在MCP支持的应用程序中直接创建、编辑和管理墨迹笔记，如cursor、Claude Desktop等。

该项目由烟花社区和Mowen共同创建。

🆕 免费安装版本已发布（适合初学者）

使用方法（以Windows为例）

下载 mowen-mcp-server windows-x64-v1.0.0.zip 并解压 mowen-mcp-server.exe
修改MCP客户端中的命令值，并替换为 mowen-mcp-server.exe 文件的路径

{
  "mcpServers": {
    "mowen-mcp-server": {
      "command": "D:\\mowen\\mowen-mcp-server.exe",
      "args": [],
      "env": {
        "MOWEN_API_KEY": "xxxxxxxxxxxxxxx"
      }
    }
  }
}

✨ 最新版本特性：支持文件上传功能！现在您可以将图像、音频和PDF文件插入到您的笔记中，支持本地文件和远程URL上传方式。

🆕 新功能预览（v0.2.0）

📁 文件上传支持

⚠️ 重要提示：文件路径必须使用绝对路径因为MCP服务器和客户端运行在不同的工作目录下。

# 本地图片文件
{
    "type": "file",
    "file_type": "image",
    "source_type": "local",
    "source_path": "C:\\Users\\用户名\\Documents\\image.jpg",  # Windows绝对路径
    "metadata": {
        "alt": "图片描述",
        "align": "center"
    }
}

# 远程音频文件（URL不受路径限制）
{
    "type": "file",
    "file_type": "audio",
    "source_type": "url",
    "source_path": "https://example.com/audio.mp3",
    "metadata": {
        "show_note": "00:00 开始\n01:30 主要内容"
    }
}

📝 引用段落

{
    "type": "quote",
    "texts": [
        {"text": "重要提醒：", "bold": true},
        {"text": "支持富文本格式的引用段落"}
    ]
}

🔗 内部链接笔记

{
    "type": "note",
    "note_id": "VPrWsE_-P0qwrFUOygGs8"
}

特性

🔗 兼容MCP协议：支持最新版MCP 1.9.1
📝 创建笔记统一富文本格式，支持段落、加粗、高亮、链接、引用和内部链接笔记
✏️ 编辑笔记统一富文本格式，完全替换笔记内容
📁 文件上传支持上传图像、音频和PDF文件，提供本地文件和远程URL选项
💬 引用段落创建支持富文本格式的引用文本块
🔗 内部链接笔记引用其他笔记并创建笔记间的关联
🔒 隐私设置为笔记设置公开、私有或规则公开权限
🔄 密钥管理重置API密钥功能
🎨 统一接口所有笔记操作均采用一致的富文本参数格式

快速开始

前提条件

Python 3.10+
Mojin Pro会员账户（API功能仅对Pro会员开放）
Mojin API密钥（在Mojin小程序中获取）

安装方法

方法1：从源代码安装（推荐）

克隆项目：

git clone https://github.com/z4656207/mowen-mcp-server.git
cd mowen-mcp-server

安装依赖项：

pip install -e .

方法2：直接安装依赖项

pip install mcp httpx pydantic

配置API密钥

Windows PowerShell

$env:MOWEN_API_KEY="你的墨问API密钥"

Linux/macOS

export MOWEN_API_KEY="你的墨问API密钥"

持久设置

创建.env文件：

MOWEN_API_KEY=你的墨问API密钥

配置MCP客户端

方式1：模块安装模式（推荐）

如果您已经使用pip install -e .安装并添加：

{
  "mcpServers": {
    "mowen-mcp-server": {
      "command": "python",
      "args": ["-m", "mowen_mcp_server.server"],
      "env": {
        "MOWEN_API_KEY": "${env:MOWEN_API_KEY}"
      }
    }
  }
}

方法2：直接指定文件路径

如果您没有安装包，可以直接指定文件路径：

{
  "mcpServers": {
    "mowen-mcp-server": {
      "command": "python",
      "args": ["绝对路径/mowen-mcp-server/src/mowen_mcp_server/server.py"],
      "env": {
        "MOWEN_API_KEY": "${env:MOWEN_API_KEY}"
      }
    }
  }
}

注意请提供：绝对路径替换为您实际的项目路径，例如：

Windows: "D:/CODE/mowen-mcp-server/src/mowen_mcp_server/server.py"
macOS/Linux: "/home/user/mowen-mcp-server/src/mowen_mcp_server/server.py"

可用工具

create_note

使用统一的富文本格式创建新的Mowen笔记

参数

paragraphs (数组，必需)：富文本段落列表，每个段落包含文本节点
auto_publish (布尔值，可选)：是否自动发布，默认为false
tags (字符串数组，可选)：笔记标签列表

支持的段落类型：

普通段落（默认）：{"texts": [...]}
引用段落：{"type": "quote", "texts": [...]}
内部链接笔记：{"type": "note", "note_id": "笔记ID"}
文档段落：{"type": "file", "file_type": "image|audio|pdf", "source_type": "local|url", "source_path": "绝对路径", "metadata": {...}}

示例段落格式：

[
  {
    "texts": [
      {"text": "普通文本"},
      {"text": "加粗文本", "bold": true},
      {"text": "高亮文本", "highlight": true},
      {"text": "链接文本", "link": "https://example.com"}
    ]
  },
  {
    "type": "quote",
    "texts": [
      {"text": "这是引用段落"},
      {"text": "支持富文本", "bold": true}
    ]
  },
  {
    "type": "note",
    "note_id": "VPrWsE_-P0qwrFUOygxxx"
  },
  {
    "type": "file",
    "file_type": "image",
    "source_type": "local",
    "source_path": "C:\\Users\\用户名\\Documents\\image.jpg",
    "metadata": {
      "alt": "图片描述",
      "align": "center"
    }
  }
]

简单文本示例：

[
  {
    "texts": [
      {"text": "这是一段简单的文本内容"}
    ]
  }
]

edit_note

使用统一的富文本格式编辑现有笔记内容

参数

note_id (字符串，必需)：要编辑的笔记ID
paragraphs (数组，必需)：富文本段落列表，将完全替换原始内容

注意：此操作将完全替换笔记的原始内容，而不是添加额外内容。支持所有段落类型（普通段落、引用段落、内部链接笔记、文件段落）。

set_note_privacy

设置笔记的隐私权限

参数

note_id (字符串)：笔记ID
privacy_type (字符串)：隐私类型（public/private/rule）
no_share (布尔值，可选)：是否禁止分享（仅适用于rule类型）
expire_at (整数，可选)：过期时间戳（仅适用于rule类型，0表示永不过期）

reset_api_key

重置Mojin API密钥

注意：此操作将立即使当前密钥失效

使用示例

创建简单文本笔记

# 通过MCP工具调用
create_note(
    paragraphs=[
        {
            "texts": [
                {"text": "今天学习了Python编程，重点是异步编程概念"}
            ]
        }
    ],
    auto_publish=True,
    tags=["学习", "Python", "编程"]
)

创建富文本笔记

# 通过MCP工具调用
create_note(
    paragraphs=[
        {
            "texts": [
                {"text": "重要提醒：", "bold": true},
                {"text": "明天的会议已改期"}
            ]
        },
        {
            "texts": [
                {"text": "详情请查看：", "highlight": true},
                {"text": "会议通知", "link": "https://example.com/meeting"}
            ]
        }
    ],
    auto_publish=True,
    tags=["会议", "通知"]
)

创建包含引用和内部链接的复杂笔记

# 通过MCP工具调用
create_note(
    paragraphs=[
        {
            "texts": [
                {"text": "项目进展报告", "bold": true}
            ]
        },
        {
            "type": "quote",
            "texts": [
                {"text": "本周完成了主要功能开发，", "highlight": true},
                {"text": "详见技术文档", "link": "https://docs.example.com"}
            ]
        },
        {
            "type": "note",
            "note_id": "VPrWsE_-P0qwrFUOygGs8"
        },
        {
            "texts": [
                {"text": "下周计划：开始测试阶段"}
            ]
        }
    ],
    auto_publish=True,
    tags=["项目", "进展", "报告"]
)

创建包含文件的笔记

# 通过MCP工具调用
create_note(
    paragraphs=[
        {
            "texts": [
                {"text": "项目截图和演示", "bold": true}
            ]
        },
        {
            "type": "file",
            "file_type": "image",
            "source_type": "local",
            "source_path": "C:\\Users\\user\\Desktop\\screenshot.png",
            "metadata": {
                "alt": "项目主界面截图",
                "align": "center"
            }
        },
        {
            "texts": [
                {"text": "演示视频（音频）："}
            ]
        },
        {
            "type": "file",
            "file_type": "audio",
            "source_type": "url",
            "source_path": "https://example.com/demo.mp3",
            "metadata": {
                "show_note": "00:00 项目介绍\n01:30 功能演示\n03:00 总结"
            }
        },
        {
            "texts": [
                {"text": "详细文档见附件："}
            ]
        },
        {
            "type": "file",
            "file_type": "pdf",
            "source_type": "local",
            "source_path": "C:\\Users\\user\\Documents\\project_doc.pdf"
        }
    ],
    auto_publish=True,
    tags=["项目", "文档", "演示"]
)

编辑笔记

# 通过MCP工具调用
edit_note(
    note_id="note_123456",
    paragraphs=[
        {
            "texts": [
                {"text": "更新：", "bold": true},
                {"text": "项目进度已完成80%"}
            ]
        },
        {
            "type": "quote",
            "texts": [
                {"text": "详细报告请查看：", "highlight": true},
                {"text": "项目文档", "link": "https://example.com/report"}
            ]
        },
        {
            "type": "note",
            "note_id": "related_note_id"
        }
    ]
)

API配额限制

根据Mowen API文档，每个接口具有以下限制：

API	配额	频率限制	描述
笔记创建	每天100次	每秒1次	成功调用计为1次，即每天可以基于API创建100个笔记
笔记编辑	每天1000次	每秒1次	成功调用计为1次，即每天可以基于API编辑1000次
笔记设置	每天100次	每秒1次	成功调用计为1次

项目结构

mowen-mcp-server/
├── src/
│   └── mowen_mcp_server/
│       ├── __init__.py       # 包初始化
│       ├── server.py         # MCP服务器主程序
│       └── config.py         # 配置管理
├── examples/
│   └── create_note/          # 创建笔记案例
├── pyproject.toml            # 项目配置
├── README.md                 # 项目文档
├── CHANGELOG.md              # 更新日志
└── 墨问API.md               # 墨问API详细文档

文档

Mowen API在线文档：https://mowen.apifox.cn/
本地API文档请参阅项目的文档中的详细Mojin API 墨问API.md文档
MCP协议文档：Model Context Protocol

常见问题

Q: 为什么模块化方法不起作用？

A: 请确保使用pip install -e .安装了包或使用直接文件路径进行了配置。

Q: 如何获得API密钥？

A: 登录Mojin小程序，在个人主页的开发者模块中找到API密钥。需要Pro会员权限。

Q: 能否编辑小程序创建的笔记？

A: 目前不支持，只能编辑通过API创建的笔记。

Q: 如何使用引用段落和内部链接笔记？

A: 使用引用段落{"type": "quote", "texts": [...]}格式，内部链接笔记使用{"type": "note", "note_id": "笔记ID"}格式。引用段落支持所有富文本格式（加粗、高亮、链接）。

Q: 如何获取内部链接笔记的note_id？

A: note_id是在创建笔记时返回的笔记ID，或者Mowen中已存在的笔记ID。请注意，只有通过API创建的笔记才能被引用。

Q: 为什么只有段落参数而没有简单的文本参数？

A: 我们统一了接口设计，使用富文本格式来支持更丰富的内容。即使是简单的文本也可以轻松地在段落中格式化：[{"texts": [{"text": "你的文本"}]}]

Q: 如何从旧版本API调用迁移？

A: 如果之前使用的是create_note(content="文本")，现在需要改为create_note(paragraphs=[{"texts": [{"text": "文本"}]}])，富文本功能保持不变。

Q: 为什么上传文件时提示“文件不存在”？

A: 必须使用绝对路径MCP服务器和客户端运行在不同的工作目录下，相对路径解析可能会失败。

✅ 正确："C:\\Users\\用户名\\Documents\\image.jpg" (Windows)
✅ 正确："/Users/用户名/Documents/image.jpg" (macOS/Linux)
❌ 错误："./image.jpg" 或 "image.jpg" (相对路径)

Q: 支持哪些文件类型？

A: 支持三种类型的文件：

图像：.gif, .jpg, .jpeg, .png, .webp (最大50MB)
音频：.mp3, .mp4, .m4a (最大200MB)
PDF (.pdf)：.pdf (最大100MB)

Q: 上传远程URL文件有哪些限制？

A: 远程URL不受路径格式限制，但文件必须公开访问并符合文件类型和大小限制。

开发贡献

欢迎提交Issue和Pull Requests！

开发环境设置

克隆项目
安装和开发依赖项：pip install -e .
设置API密钥环境变量
运行测试

许可证

本项目采用MIT许可证。详情见LICENSE文档。

免责声明

本项目是由个人开发的第三方工具，与官方Mowen平台无关。请在使用前确保遵守Mowen的服务条款。