mcp-notes-server

mcp-notes-server

一个精简的、免费且开源的 Python Model Context Protocol (MCP) 服务，为任何兼容 MCP 的 AI 助手提供持久化笔记本：创建笔记、列出笔记并搜索笔记，所有内容都存储在由你掌控的本地纯 JSON 文件中。

基于官方 mcp Python SDK（FastMCP）构建。无需数据库、云服务或账号。你的笔记绝不会离开你的设备。

工具

工具	功能
create_note	创建笔记，需提供标题（必填，≤120 个字符）和正文（≤10,000 个字符）。返回包含 ID 和时间戳的已保存记录。
list_notes	列出已保存的笔记，按时间从新到旧排序（可配置数量，1–500）。
search_notes	不区分大小写地搜索标题和正文中的关键词。

快速开始

git clone <this-repo-url>
cd mcp-notes-server
pip install -r requirements.txt
python server.py

服务通过 stdio 使用 MCP。可从任何 MCP 宿主连接它——请参阅下方和 examples/ 中的配置示例。

Claude Desktop

将以下内容添加到你的 claude_desktop_config.json（请参阅 examples/claude_desktop_config.example.json）：

{
  "mcpServers": {
    "notes-server": {
      "command": "python",
      "args": ["/absolute/path/to/mcp-notes-server/server.py"]
    }
  }
}

通用 MCP 宿主

请参阅 examples/mcp-client-config.generic.json——同样的 stdio 命令/参数模式适用于大多数宿主。

试用

1. 连接你的 MCP 宿主并询问：“创建一条标题为‘购物清单’的笔记，内容为牛奶、鸡蛋和咖啡。”
2. 询问：“搜索我的笔记，查找鸡蛋。”
3. 打开 notes.json（会自动在 server.py 旁创建），查看原始存储内容——它只是一个 JSON 文件。

工作原理

• 存储辅助函数负责加载/保存单个 notes.json 文件；保存操作是原子的（先写入临时文件，再替换原文件）。
• 每个工具都会验证输入（标题为必填且有长度上限、正文有长度上限、搜索查询为必填）。
• 工具函数是使用 @mcp.tool() 装饰的普通 Python 函数——类型注释会转换为工具输入架构。整个服务是一个易读的文件（约 150 行），旨在方便复制和改造。

运行烟雾测试（无需 MCP 宿主）：

python tests/smoke_test.py

已通过真实 MCP 协议（stdio，官方 SDK v1.x）完成端到端验证——工具已列出，笔记已创建、搜索和列出：请参阅 tests/mcp_e2e_test.py，并在运行 pip install -r requirements.txt 后自行测试。请注意，requirements 将版本限定为 mcp<2：2.x SDK 重命名了 FastMCP，而此代码面向 v1 API。

范围与安全

• 仅限本地。 此服务只会读取/写入其所在文件夹中的一个 JSON 文件。它不会发起网络请求，也没有删除工具——这是有意设计的入门范例。
• 请将其视为学习/原型开发基础，而非经过加固的生产服务：没有身份验证（stdio 服务由宿主以你的用户身份启动），除原子文件替换外没有并发锁定。

获取完整套件

此免费服务是 MCP Server Starter Templates 套件中的三个入门模板之一——完整套件还包含一个只读 SQLite 查询服务（附带经过测试的 SQL 注入防护：仅允许 SELECT 的验证）和一个网页摘要服务骨架，以及适用于这三者的客户端配置、测试清单和安全说明，帮助你推动 MCP 服务走向生产环境。

→ MCP Server Starter Templates（以及更多 AI Agent 工具：AgentProof 测试套件、LLM/RAG 评估套件、经过验证的 Agent 数据集）：bradray2.gumroad.com

付费套件的免费样例可在配套仓库 ai-agent-tools-free-samples 中获取。

许可证

MIT——请参阅 LICENSE。使用它、派生它、发布它。

版权所有 (c) 2026 Brad Lucas。