NoteGen MCP服务器：让AI工具直接写入本地Markdown笔记

NoteGen 是一个以本地 Markdown 笔记为核心的整理工具，它解决的是“把零散资料变成长期可用结构化笔记”这件事。真正让 NoteGen 发挥价值的并不是打开软件手动录入，而是让它能被各种 AI 工具直接调用。MCP（Model Context Protocol，模型上下文协议）就是这个连接层：通过一个 NoteGen MCP 服务器，支持 MCP 的客户端可以把对话总结、网页摘录、临时想法直接写入 NoteGen 的笔记目录，并按文件夹、标签和全文搜索完成整理。下面这份教程会从概念说起，逐步搭建一个最小可用的 NoteGen MCP 服务，最后覆盖客户端接入、功能验证、常见报错排查和生产化建议。完成之后，你可以在支持 MCP 的桌面客户端里用一句自然语言完成一次笔记整理。

1. MCP 为什么是 NoteGen 接入 AI 工具的关键

1.1 NoteGen 负责什么

在常见的个人知识管理流程里，信息收集通常很容易，难的是整理。一段对话摘要、一篇网页文章、一次会议记录，如果只是堆在一个文档里，后续几乎不会被检索。NoteGen 的思路是把这些内容转换为 Markdown 笔记，用文件夹做粗分类，用标签做交叉维度，再通过文件名和正文让搜索变得可用。

在集成开始之前，要先明确 NoteGen 的能力边界：它负责笔记的存储结构、文件命名、目录组织、标签格式和搜索语义。AI 工具不需要知道笔记文件放在哪里，也不需要掌握 Markdown 语法细节，它只需要调用一个“创建笔记”的工具，并告诉 NoteGen 标题、内容、分类和标签就够了。这个分工正是 MCP 擅长处理的场景。

1.2 MCP 的工作模式

MCP 是客户端与服务端之间的一个开放协议。客户端是 AI 应用，例如 Claude Desktop、Cline、Cherry Studio 这类支持 MCP 的桌面软件；服务端是一个独立进程或 HTTP 服务，负责暴露能力。服务端把能力声明为 Tools、Resources、Prompts 三类资源，其中 Tools 是本次教程的重点。

当用户在客户端里说“把这段内容整理成 NoteGen 笔记”时，客户端会理解出用户意图，查看当前连接的 MCP 服务端暴露了哪些工具，再根据工具描述决定是否调用。调用请求会通过 JSON-RPC 发送给服务端，服务端执行真实操作后返回结果。客户端把结果转成自然语言回复用户。这个过程中，AI 模型并不需要预先掌握 NoteGen 的实现细节。

与各家厂商自带的 Function Calling 相比，MCP 的价值在于协议开放、配置驱动、可动态发现工具。只要客户端支持 mcpServers 配置段，就可以接入同一个 NoteGen 服务端，不需要为每个应用单独开发插件。对个人知识管理来说，这意味着笔记能力可以被多个 AI 工具复用。

1.3 为什么不直接让 AI 输出 Markdown 文件

有读者会问：直接让 AI 生成 Markdown 再保存，似乎也能达到类似效果。这个思路对少量手动操作可行，但作为长期机制有四个问题。

第一，权限不可控。AI 一旦被授予写文件的能力，就会决定文件写到哪里，可能把笔记混入项目目录或临时目录。第二，格式不稳定。不同回答里标签位置、标题层级、元信息格式都可能变化，后续检索无法依赖固定结构。第三，缺少校验。文件名里出现路径分隔符、重复标题覆盖旧文件、中文编码不一致，这些问题在直接写文件时很难统一处理。第四，无法扩展。直接写文件只适用于本地，如果以后希望远程团队共享笔记，每个客户端都要重新实现一套逻辑。

通过 MCP 工具暴露 NoteGen 能力后，上述问题都被收敛到服务端。服务端可以统一做路径清理、目录映射、编码转换、模板补全和冲突保护。AI 工具只负责表达意图，NoteGen 服务端负责执行规则。

2. 准备环境与设计笔记目录

2.1 运行环境清单

下面这组环境用于在本地跑通完整流程。学习环境和生产环境会有差异，这一点会在第 7 节进一步说明。

安装 SDK 的命令在不同环境略有差异。通常可以这样做：

bash复制pip install mcp

如果机器上同时存在多个 Python 版本，建议先确认使用的是哪个解释器：

bash复制python --version
python -m pip --version

这里的版本检查很重要。后续 MCP 客户端配置里写的是哪个 Python 命令，服务端就必须由同一个解释器启动。如果客户端用 python 启动，而依赖只装在 python3 对应的环境里，连接会一直失败。

2.2 NoteGen 笔记目录设计

建议先规划一个清晰的笔记根目录。我倾向于采用“分类文件夹 + 标签 + 时间可选”的结构：

text复制NoteGen/
  notes/
    inbox/          # 未整理的临时笔记
    learning/       # 学习类笔记
    work/           # 工作相关笔记
    meeting/        # 会议记录

文件名不要直接使用未经处理的标题。标题中可能包含斜杠、冒号、反斜杠，直接写入文件系统会出错。服务端应该对文件名做清洗，把路径分隔符替换为下划线，必要时加上日期或短 ID 避免同名覆盖。

一个可用的命名规则是：YYYY-MM-DD-标题.md，也可以保持纯标题但增加重名检测。具体规则不唯一，关键是服务端有且只有一个统一约定。这样以后全文搜索、标签统计和批量导出都会稳定很多。

2.3 MCP 客户端配置入口

多数支持 MCP 的桌面客户端都提供 mcpServers 配置入口。配置内容是一段 JSON，结构是协议规定的固定写法。一个最小配置如下：

json复制{
  "mcpServers": {
    "notegen": {
      "command": "python",
      "args": ["/absolute/path/to/notegen_server.py"],
      "env": {
        "NOTEGEN_ROOT": "/absolute/path/to/NoteGen/notes"
      }
    }
  }
}

客户端启动时会根据 command 和 args 拉起服务端进程，通过标准输入输出进行通信。env 段用来向服务端注入环境变量，这里把笔记根目录作为环境变量传入，而不是写在代码里，后续迁移目录时只需要改配置。

这个结构在不同客户端的填写位置可能不同，但字段含义是一致的。连接失败时，优先检查 command、args、env 三个字段是否与实际路径一致。

3. 用 Python 实现 NoteGen MCP 服务端

3.1 初始化服务与目录

下面以一个名为 notegen_server.py 的文件为例，实现 NoteGen 的 MCP 服务端。代码使用 MCP Python SDK 提供的 FastMCP 封装。说明一点：SDK 的导入路径在不同版本可能有调整，下面示例中采用的 mcp.server.fastmcp 在近几个版本中是常见路径。如果安装的 SDK 改成 fastmcp 包，只需同步调整第一行导入。

python复制# notegen_server.py
from datetime import datetime
from pathlib import Path

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("notegen")

NOTES_ROOT = Path(__file__).resolve().parent

def current_time() -> str:
    return datetime.now().strftime("%Y-%m-%d %H:%M:%S")

def safe_name(name: str) -> str:
    cleaned = name.strip()
    cleaned = cleaned.replace("../", "").replace("..\\", "")
    cleaned = cleaned.replace("/", "_").replace("\\", "_")
    cleaned = cleaned.replace(":", "_").replace("*", "_")
    return cleaned or "untitled"

代码里有两点要解释。NOTES_ROOT 在示例中取的是脚本所在目录，更合理的做法是从环境变量读取，稍后会改成：

python复制import os

NOTES_ROOT = Path(
    os.environ.get("NOTEGEN_ROOT", str(Path(__file__).resolve().parent))
)

safe_name 用于文件名清洗。把路径分隔符、冒号和星号等非法字符替换成下划线，避免模型在标题里带入特殊字符。这里的清洗逻辑是学习环境的简化版，生产环境还应该包含长度限制、保留字处理和重名检测。

3.2 注册创建笔记工具

以下是 create_note 工具。它接收标题、正文、标签和文件夹名，在笔记根目录下创建 Markdown 文件，返回文件路径作为执行结果。

python复制@mcp.tool()
def create_note(
    title: str,
    content: str,
    tags: str = "",
    folder: str = "inbox"
) -> str:
    """在 NoteGen 中创建一篇 Markdown 笔记。
    使用场景：把对话总结、网页摘录、临时想法保存为长期笔记。
    title 是笔记标题，content 是 Markdown 正文，tags 是逗号分隔的标签，
    folder 是笔记分类文件夹。
    """
    root = NOTES_ROOT / safe_name(folder)
    root.mkdir(parents=True, exist_ok=True)

    file_name = f"{safe_name(title)}.md"
    file_path = root / file_name

    header = [
        f"# {title}",
        "",
        f"> created_at: {current_time()}",
        f"> tags: {tags}",
        "",
    ]
    text = "\n".join(header) + "\n" + content.strip() + "\n"

    file_path.write_text(text, encoding="utf-8")
    return f"笔记已创建：{file_path}"

创建成功后返回的是文件绝对路径。客户端会把这段文字原样展示给用户，用户直接复制路径就能打开文件查看。

这里的关键点在函数说明。工具说明不是给用户看的，而是给模型看的。模型需要根据描述判断“什么时候应该调用这个工具”。如果描述写成“创建笔记”四个字，模型在用户表达“整理一下刚才的内容”时可能不确定该不该调用。更好的描述应该点明适用场景、参数含义和可选默认值。

3.3 注册搜索笔记工具

只有创建没有检索，笔记就变成了只写不读的黑洞。这里再注册一个 search_notes 工具，简单扫描笔记根目录下的 Markdown 文件，按关键字做大小写不敏感的匹配，返回命中文件名和首段摘要。

python复制@mcp.tool()
def search_notes(keyword: str, folder: str = "") -> str:
    """在 NoteGen 中搜索笔记。
    当用户想查找历史笔记、复习旧知识或确认某主题是否有记录时调用。
    keyword 是搜索关键字，folder 可以限定到某个分类文件夹。
    """
    root = NOTES_ROOT / safe_name(folder) if folder else NOTES_ROOT
    results = []

    for md_file in sorted(root.rglob("*.md")):
        try:
            text = md_file.read_text(encoding="utf-8")
        except UnicodeDecodeError:
            continue
        if keyword.lower() not in text.lower():
            continue
        lines = [line for line in text.splitlines() if line.strip()]
        snippet = lines[1][:80] if len(lines) > 1 else ""
        results.append(f"{md_file.relative_to(NOTES_ROOT)} | {snippet}")

    if not results:
        return f"没有找到包含“{keyword}”的笔记。"
    return "\n".join(results[:20])

搜索功能做得比较简单，适合本地小规模笔记。真正大规模使用后，建议改为基于文件名、标签和标题的索引检索。但 MCP 工具边界不变，模型需要的只是一个“按关键字找笔记”的能力。

3.4 启动服务端

服务端最后需要启动监听。FastMCP 实例有一个 run() 方法，启动后会通过标准输入输出与客户端通信。

python复制if __name__ == "__main__":
    mcp.run()

此时手动运行：

bash复制python notegen_server.py

终端不会有太多输出，进程会驻留等待消息。这是一个正常的启动结果。如果终端立刻退出，说明代码有语法错误或依赖缺失，需要先解决到这一步再接入客户端。

注意：MCP 的 stdio 传输方式使用的是标准输出，服务端代码里不要用 print 输出调试日志。任何非协议内容出现在标准输出，都会干扰客户端解析 JSON-RPC 消息。调试日志应写入文件，或使用标准错误输出。

4. 在 MCP 客户端中连接并验证

4.1 填写 mcpServers 配置

以支持 MCP 的桌面客户端为例，在配置区域找到 mcpServers 入口，填入下面的内容：

json复制{
  "mcpServers": {
    "notegen": {
      "command": "python",
      "args": ["/absolute/path/to/notegen_server.py"],
      "env": {
        "NOTEGEN_ROOT": "/absolute/path/to/NoteGen/notes"
      }
    }
  }
}

Windows 系统的 command 一般是 python，注意路径中的反斜杠需要转义或用正斜杠。macOS 和 Linux 下如果 Python 命令名是 python3，就要写成 python3，不能照抄这个 JSON，否则会报找不到命令。

NOTEGEN_ROOT 在示例里可以省略，省略时服务端使用脚本所在目录。但推荐显式设置，这样脚本文件位置和笔记目录可以分开管理，后续更新服务端代码不会影响笔记数据。

4.2 验证连接状态

配置保存后，重启客户端，或触发一次客户端对 MCP 服务器列表的刷新。大多数客户端会在设置面板或服务器列表里显示 notegen 的状态。

可以按顺序做三个验证：

1. 查看 notegen 是否从“连接中”变成“已连接”或类似状态。
2. 在会话中主动提到“查找笔记”，看模型是否调用 search_notes。
3. 在会话中要求“创建一条测试笔记”，看返回是否包含文件路径。

如果客户端提供 MCP Inspector 等调试工具，可以绕过界面直接查看服务端暴露的工具列表。命令一般是：

bash复制mcp dev notegen_server.py

这会启动一个本地调试面板，在里面检查 create_note 和 search_notes 是否存在，直接手动传入参数调用一次，确认服务端返回结构正常。

4.3 用一句话完成笔记整理

连接成功后，实际使用会非常自然。在对话窗口里输入类似这样的指令：

text复制把刚才关于 MCP 的讨论整理成一篇 NoteGen 笔记。
标题：MCP 接入 NoteGen 的核心流程
文件夹：learning
标签：mcp,notegen
内容按三步结构写：概念、配置、验证。

客户端会把这条指令拆解成一次 create_note 调用，参数对应标题、正文、文件夹和标签。整个过程不需要打开编辑器手动新建文件，也不需要复制粘贴。NoteGen 服务端看到的是一个标准函数调用，它并不知道也不关心是哪个客户端发出的。

5. 典型整理流程、参数含义与结果演示

5.1 一次完整的输入到落盘流程

为了便于理解参数，这里演示一次完整流程。

用户输入：

text复制请把下面内容整理成笔记：
MCP 是模型上下文协议，用于连接 AI 客户端与外部工具。服务端暴露工具，客户端按描述调用。
标题：MCP 协议笔记
文件夹：learning
标签：mcp,protocol

模型判断后调用：

json复制{
  "tool": "create_note",
  "arguments": {
    "title": "MCP 协议笔记",
    "content": "MCP 是模型上下文协议，用于连接 AI 客户端与外部工具。服务端暴露工具，客户端按描述调用。",
    "tags": "mcp,protocol",
    "folder": "learning"
  }
}

服务端创建文件后返回：

text复制笔记已创建：/absolute/path/to/NoteGen/notes/learning/MCP 协议笔记.md

生成的文件内容大致如下：

markdown复制# MCP 协议笔记

> created_at: 2025-06-01 14:22:01
> tags: mcp,protocol

MCP 是模型上下文协议，用于连接 AI 客户端与外部工具。服务端暴露工具，客户端按描述调用。

5.2 参数含义速查

下面这张表面向实际使用场景，说明每个参数的取舍。

content 的长度需要特别关注。模型生成的内容一次可能很长，如果全部塞进单次工具调用，容易在传输层被截断或超时。生产环境建议把内容拆成创建主笔记、追加子章节，或者在服务端实现“先创建后追加”的工具组合。本地学习环境单条 2000 字内通常没有问题。

5.3 搜索结果验证

整理完笔记后，可以用 search_notes 验证检索。对话输入：

text复制搜索 NoteGen 目录里和 MCP 有关的笔记

模型会调用 search_notes，参数 keyword 为 “MCP”。返回结果是命中文件列表和摘要：

text复制learning/MCP 协议笔记.md | MCP 是模型上下文协议，用于连接 AI 客户端与外部工具。

如果希望缩小范围，可以追加 folder 参数，搜索工具会把范围限制到指定分类。这个流程验证了“创建后可检索”，也是个人知识管理的基本闭环。

6. 常见问题与排查路径

6.1 问题速查表

实际接入时，很多问题并不在代码逻辑，而在环境配置。下面列出高频问题和对应处理方式。

6.2 按链路排查

出现问题时，按以下顺序排查比较高效。

1. 先手动运行 python notegen_server.py，确认服务能够启动且不立即退出。
2. 检查客户端配置中的 command 是否能在终端里找到。可以执行 which python 或 where python 确认实际命令名。
3. 确认 args 里的脚本路径是绝对路径，路径中不含需要转义的字符。
4. 确认笔记根目录存在且有写权限。手动在目录里创建一个测试文件，排除权限问题。
5. 再回到客户端，删除旧的 MCP 服务器配置后重新添加一次，避免配置修改后未生效。

如果服务端依赖 mcp 包，但启动时报 ModuleNotFoundError，说明客户端使用的 Python 环境与安装依赖的环境不一致。可以改用绝对路径形式的解释器，例如 /usr/local/bin/python3，或者用虚拟环境中的 python 路径。

6.3 stdio 输出污染问题

这是 MCP stdio 模式最隐蔽的一个坑。很多开发者在服务端代码里写 print("server started")，结果客户端始终无法正常连接。

原因在于 stdio 模式中，标准输出是协议通道的一部分。MCP 客户端通过标准输出读取 JSON-RPC 消息，任何额外文本都会破坏解析。解决办法是不要用 print 输出普通日志，改为写入日志文件：

python复制import sys

def log_to_stderr(msg: str) -> None:
    sys.stderr.write(f"[notegen] {msg}\n")

这样做既保留调试信息，又不污染协议通道。在无法连接的问题里，很大比例是这一类非协议输出造成的。

7. 最佳实践与扩展方向

7.1 发布前检查清单

每次修改服务端代码或更换运行环境时，建议按清单确认。

• [ ] 服务端脚本能手动启动，且没有语法错误。
• [ ] mcp 依赖已安装到客户端使用的同一个 Python 环境。
• [ ] 配置中 command 与 Python 实际命令名一致。
• [ ] NOTEGEN_ROOT 指向正确的笔记根目录，且目录存在。
• [ ] 文件名清洗、UTF-8 编码和写权限已验证。
• [ ] 客户端能看到 create_note 和 search_notes 两个工具。
• [ ] 实际测试一次创建和一次搜索，两次都返回预期结果。

这套清单同样适用于以后新增工具时的回归验证。不要只在能启动的时候检查，要覆盖“创建、检索、异常输入”三个方向。

7.2 安全边界与会话控制

个人本地场景相对安全，但仍需要建立边界。创建笔记时要做文件名清洗，防止路径穿越；更新笔记时要先做搜索或读取，不能盲目覆盖；服务端的工具描述要明确适用范围，避免模型在无关场景下误调用。

如果以后增加更新和删除类工具，建议先做备份或软删除。例如更新前把旧版本重命名到 .history 目录，删除时先移动到 .trash。这种机制在可控的笔记量下成本很低，但能避免一次误指令造成不可恢复的损失。

7.3 从本地到团队的扩展方向

本教程使用的是 stdio 本地进程模式，适合个人电脑上一个人使用。如果要给团队使用，通常会把 MCP 服务端改造成 HTTP 传输方式，客户端通过远程地址连接。这时候安全模型发生变化，不能再依赖本机文件权限，至少要补充：

• 传输层加密，例如 HTTPS。
• 服务端鉴权，例如访问令牌或用户身份校验。
• 请求日志，便于追踪谁在什么时间创建或修改了笔记。
• 限流和长度限制，防止单个模型上下文耗尽服务资源。
• 数据备份策略，服务端不再只是本机进程。

这些措施不是 MCP 协议里强制绑定的，但一旦开放远程访问，就应该按服务端应用的标准来对待。NoteGen 的价值在于生产力，而不是把笔记目录直接变成无鉴权接口。

7.4 更进一步的整理能力

最小接入跑通后，可以继续扩展服务端工具集。比较实用的方向包括：自动标签生成、重复笔记检测、按日期归档、批量导出、RSS 或邮件转笔记、把搜索结果包装成结构化返回供客户端分析。每个新工具都要遵守同样的原则：输入有默认值、说明写清楚、返回可理解、路径可控。

从更大的视角看，MCP 接入 NoteGen 的意义在于把“AI 生成内容”和“知识沉淀”这两个环节连接起来。真正有价值的不是某一次对话生成了完美回答，而是这些回答能被稳定地保存、检索、复用到下一次提问中。对个人用户来说，先跑通最小闭环，再逐步增加工具和约束，是比较稳妥的落地路径。