AI导哈

本地笔记MCP服务器

一个将本地笔记文件夹暴露为只读工具的Python MCP服务器，支持列出、搜索和获取笔记内容。

  • by ShakedP621
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 ShakedP621/local-notes-mcp-server

使用说明

本地Notes MCP服务器

小型Python模型上下文协议（MCP）服务器，将本地注释文件夹公开为三个 只读的 工具：

  • list_notes
  • search_notes （仅限文件名）
  • get_note

目标是用最少的代码展示如何：

  • 使用官方 mcp Python包。
  • 将其连接到真正的文件系统文件夹。
  • 在本地或Docker中运行它，并将MCP客户端指向它。

功能（和非目标）

它的作用

  • MCP服务器通过stdio。
  • 从单个根文件夹读取笔记。
  • 支持嵌套子目录。
  • 文本格式： .md, .txt, .rst, .org.
  • 三个工具：
    • list_notes → 摘要(path, name, extension, size_bytes, modified_iso)
    • search_notes → 简单的文件名子字符串搜索
    • get_note → 按相对路径排列的全文

它故意做什么 不 做

  • 无写API（无创建/更新/删除）。
  • 无内容/RAG/语义搜索（仅文件名）。
  • 无身份验证、用户帐户或多租户。

开始（本地）

要求：

  • python 3.11+

  • git, pip

    克隆https://github.com/ShakedP621/local-notes-mcp-server.git

    cd本地notes mcp服务器

    python-m venv.venv

    Linux/macOS

    source.ven/bin/activate

    Windows（PowerShell）

    .venv\Scripts\Activate.ps1

    pip安装-e。

    python-m local_notes_mcp

您应该看到类似以下内容：

INFO     Using NOTES_ROOT: /path/to/notes
INFO     Starting Local Notes MCP Server (notes_root=/path/to/notes)

配置

服务器需要一个 笔记根 目录。它解决了 NOTES_ROOT 按照以下顺序：

  1. NOTES_ROOT env 是
  2. LOCAL_NOTES_MCP_NOTES_ROOT env-var（便于本地开发）
  3. demo-notes/ 在回购中（如果存在）
  4. /notes （Docker的默认设置不错）

这些工具使用的路径是：

  • 相对于 NOTES_ROOT
  • 始终采用POSIX风格 /，即使在Windows上

示例：

  • root-note.md
  • python/asyncio.md
  • projects/mcp/design-notes.txt

码头工人

塑造形象：

docker build -t local-notes-mcp-server .

使用repo的演示说明（Linux/macOS）运行：

docker run --rm -it \
  -e NOTES_ROOT=/notes \
  -v "$(pwd)/demo-notes:/notes:ro" \
  local-notes-mcp-server

使用自己的笔记运行（Linux/macOS）：

docker run --rm -it \
  -e NOTES_ROOT=/notes \
  -v "/absolute/path/to/your/notes:/notes:ro" \
  local-notes-mcp-server

使用您自己的笔记运行（Windows PowerShell）：

docker run --rm -it `
  -e NOTES_ROOT=/notes `
  -v "C:\Users\you\notes:/notes:ro" `
  local-notes-mcp-server

与MCP客户端一起使用

服务器通过MCP进行通话 stdin/stdout:

  • 从读取请求 stdin
  • 将回复写入 stdout
  • 日志到 stderr

通过Python运行它的典型客户端配置（伪JSON）可能如下：

{
  "mcpServers": {
    "local-notes": {
      "command": "python",
      "args": ["-m", "local_notes_mcp"],
      "env": {
        "LOCAL_NOTES_MCP_NOTES_ROOT": "/path/to/your/notes"
      }
    }
  }
}

或者通过Docker：

{
  "mcpServers": {
    "local-notes-docker": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "NOTES_ROOT=/notes",
        "-v", "/absolute/path/to/your/notes:/notes:ro",
        "local-notes-mcp-server"
      ]
    }
  }
}

调整路径和配置形状，以匹配您的MCP客户端和本地设置。

开发-皮棉、格式、类型检查

本项目使用：

典型命令（来自repo根目录）：

ruff check src tests
ruff format src tests
mypy src

相关 MCP