AI导哈

笔记管理服务器

一个用于管理个人笔记的Model Context Protocol (MCP)服务器，支持结构化标签和Markdown格式，可与Claude Desktop集成，提供无缝的笔记记录功能。

  • by StarrStack
  • Python
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 StarrStack/mcp-notes

使用说明

MCP笔记服务器

一种模型上下文协议（MCP）服务器，用于管理具有结构化标记和标记支持的个人笔记。该服务器与Claude Desktop集成，在人工智能对话期间提供无缝的笔记功能。

特性

  • 结构化标记：用于类别、类型、优先级和主题的受控词汇表，具有动态模式管理功能
  • Markdown支持：用markdown格式写丰富的笔记
  • 高级搜索：使用标记过滤器、标题搜索和日期范围过滤查找笔记
  • 导出功能：将单个笔记或整个收藏导出到markdown文件
  • 动态模式：以编程方式向任何维度添加新标记
  • JSON存储：具有原子写入的简单基于文件的持久化
  • MCP集成：通过stdio传输与Claude Desktop原生协作
  • 网络界面：在带有反向链接和标签导航的wiki风格的web界面中浏览笔记

安装

先决条件

  • Python 3.10或更高版本 （MCP SDK要求）
  • Claude桌面应用程序

检查你的Python版本:

python3 --version

如果你有Python 3.9或更早版本，请安装更新版本：

  • macOS: brew install python@3.11 （要求 家酿)
  • 替代：从下载 python.org

设置

  1. 克隆或下载此存储库

  2. 安装依赖项:

    # If you installed Python 3.11 via Homebrew, use:
python3.11 -m pip install -r requirements.txt

# Or use whichever Python 3.10+ you have installed

  3. 配置Claude桌面:

    编辑您的Claude Desktop配置文件：

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • 视窗: %APPDATA%\Claude\claude_desktop_config.json

    添加以下配置：

    {
  "mcpServers": {
    "notes": {
      "command": "python3.11",
      "args": ["/absolute/path/to/MCPNotes/server.py"]
    }
  }
}

    重要:

    • 替换 python3.11 使用Python 3.10+命令（使用 which python3.11 验证）
    • 替换 /absolute/path/to/MCPNotes/server.py 与您的实际路径 server.py 文件

  4. 重新启动克劳德桌面 加载服务器

  5. 验证安装: 打开克劳德桌面，问：“你有什么可用的工具？” 您应该看到列出的笔记工具。

数据模型

注释结构

每张便条包含：

  • ID：唯一UUID
  • 标题：注释标题
  • 内容：Markdown格式的内容
  • 标签：结构化标签（类别、类型、优先级、主题）
  • 创建：ISO-8601时间戳
  • 更新：ISO-8601时间戳

标记架构

默认标记模式包括：

  • 类别 （必填，正好一个）： work, personal, learning
  • 类型 （必填，正好一个）： project, idea, reference, todo, note
  • 优先级 （必填，正好一个）： active, soon, someday, eventually, maybe, not-actionable
  • 话题 （可选，零个或更多）： mcp, ai, coding, design

您可以使用 add_tags_to_schema 工具，或手动编辑 notes.json.

可用工具

1. get_tag_schema

获取显示所有有效标签的完整标签架构。

示例：“显示标记架构”

2. create_note

使用已验证的标签创建新笔记。

示例：“创建一个名为“MCP服务器创意”的笔记，内容为“使用MCP构建笔记服务器”，类别：学习，类型：项目，优先级：活动，主题：MCP，编码”

3. update_note

更新现有注释（支持部分更新）。

示例：“更新note[id]并将优先级更改为'很快'”

4. delete_note

按ID删除注释。

示例：“删除注释[id]”

5. read_note

阅读特定笔记的全部内容。

示例：“显示注释[id]”

6. find_notes_by_tags

使用标签过滤、标题搜索和日期过滤器（所有过滤器的and逻辑，或主题内的and逻辑）搜索笔记。

参数:

  • 标签过滤器： category, type, priority, topics
  • 标题搜索： title_contains （不区分大小写的子字符串匹配）
  • 日期筛选器： created_after, created_before, updated_after, updated_before （ISO-8601时间戳）

示例:

  • “查找类别为“工作”、优先级为“活动”的所有笔记”
  • “查找有关mcp或ai主题的所有注释”
  • “查找标题中带有‘MCP’的注释”
  • “查找2025-01-01之后创建的笔记”
  • “显示上周更新的笔记”
  • “显示所有笔记”（无过滤器=全部返回）

7. list_tags

列出当前正在使用的所有标签及其计数。

示例：“我在笔记中使用了哪些标签？”

8. add_tags_to_schema

动态地向架构维度添加新标记。

参数:

  • dimension：其中之一 category, type, priority，或 topics
  • tags：要添加的标记值数组

示例:

  • “添加一个名为“研究”的新类别”
  • “在优先级维度中添加‘紧急’和‘积压’”
  • “添加主题：python、javascript、rust”

9. export_note_to_markdown

将单个注释导出到markdown文件。

参数:

  • id：注意要导出的UUID
  • output_path：可选的自定义输出文件路径（如果未提供，则自动生成）

示例:

  • “将注释[id]导出到markdown”
  • “将此笔记导出到/Users/me/Desktop/note.md”

10. export_all_notes_to_markdown

将所有笔记导出到目录中的markdown文件。

参数:

  • output_dir：可选输出目录路径（默认为 exported_notes/)

示例:

  • “将我的所有笔记导出到markdown”
  • “将所有笔记导出到/Users/me/Desktop/my_notes”

用法示例

以下是在Claude Desktop中与笔记交互的一些自然方式：

创建笔记:

  • “我想记下我正在学习的MCP协议”
  • “为我的项目想法创建注释”

查找笔记:

  • “显示我所有的活动工作项目”
  • “我有什么学习笔记？”
  • “查找有关人工智能或编码的注释”
  • “查找标题中带有‘Python’的注释”
  • “显示我本周创建的笔记”
  • “查找1月1日之后更新的笔记”

管理笔记:

  • “将note[id]的优先级更改为‘soon’”
  • “更新我的MCP笔记的内容”
  • “删除那张旧纸条”

组织:

  • “我使用什么标签？”
  • “显示标记架构”
  • “列出我所有的活动待办事项”
  • “添加一个名为“健康”的新类别”
  • “将‘python’和‘rust’添加到我的主题中”

出口:

  • “将我的所有笔记导出到markdown”
  • “将注释[id]导出到markdown文件”
  • “将所有笔记导出到我的桌面”

网络界面

除了MCP服务器与Claude Desktop的集成外，该项目还包括一个基于Flask的web界面，用于以wiki风格的格式浏览笔记。

特性

  • Wiki链接：使用以下命令在笔记之间创建连接 [[Note Title]] 语法
  • 导入链接：查看哪些笔记链接到当前笔记
  • 标记导航：按类别、类型、优先级和主题浏览笔记
  • 搜索：在标题和内容之间进行全文搜索
  • 最近的笔记：查看最近更新的笔记
  • Markdown渲染：代码块语法高亮显示，呈现美观

运行Web界面

  1. 安装web依赖项 （如果尚未安装）：

    python3.11 -m pip install -r requirements.txt

  2. 启动web服务器:

    python3.11 web_server.py

  3. 打开浏览器: 访问http://localhost:5000

web界面直接从相同的 notes.json MCP服务器使用的文件，因此刷新页面时，在Claude Desktop中所做的任何更改都会立即显示。

有关web界面功能和用法的详细信息，请参阅 WIKI_README.md.

文件结构

mcp-notes/
├── notes.json          # Data storage (auto-created)
├── server.py           # Main MCP server
├── web_server.py       # Flask web interface
├── templates/          # HTML templates for web UI
│   ├── base.html
│   ├── index.html
│   ├── note.html
│   ├── tag.html
│   ├── search.html
│   └── all.html
├── static/
│   └── style.css       # Web interface styling
├── README.md           # This file
├── WIKI_README.md      # Web interface documentation
└── requirements.txt    # Python dependencies

数据存储

  • 所有笔记都存储在 notes.json 与位于同一目录中 server.py
  • 首次运行时，会使用默认架构自动创建该文件
  • 原子写入防止数据损坏
  • 所有数据在服务器重启后仍然存在

故障排除

服务器未出现在Claude Desktop中:

  • 验证中的路径 claude_desktop_config.json 绝对正确
  • 检查Python是否在您的PATH中
  • 完全重新启动克劳德桌面

标签验证错误:

  • 使用 get_tag_schema 查看有效标签
  • 确保提供所需的标签（类别、类型、优先级）
  • 检查所有标记是否与架构完全匹配（区分大小写）

注释不持久:

  • 验证 notes.json 存在并且可写
  • 检查目录上的文件权限

未来的增强功能

未来版本的潜在改进：

MCP服务器:

  • 笔记内容内的全文搜索（跨markdown搜索）
  • 将现有的markdown文件作为注释导入
  • SQLite后端可在大型笔记集合中实现更好的性能
  • 笔记存档/软删除
  • 标签别名和同义词
  • 批量操作（批量更新、带过滤器的批量导出）
  • 注释模板

网络界面:

  • 音符连接的图形可视化
  • 实时编辑功能
  • 黑暗模式主题切换
  • 使用正则表达式和标签组合进行高级搜索
  • 自动完成wiki链接
  • 标签管理UI

许可证

GPL-3.0许可证-您可以根据需要自由修改和扩展此服务器。

相关 MCP