Skip to main content
Glama
sixbenzene

MCP Notes Server

by sixbenzene
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

MCP Notes Server

基于 MCP (Model Context Protocol) 的个人笔记管理服务，让 AI Agent 通过标准协议远程读写、搜索和编辑 Markdown 笔记。

功能

工具

说明

create_note

创建新笔记

append_note

追加内容（支持自动时间戳）

read_note

读取笔记（支持按行范围，返回 mtime 用于冲突检测）

delete_note

删除笔记

search_notes

跨文件关键词搜索，返回上下文

replace_in_note

精确文本替换（支持 mtime 校验）

list_notes

列出目录内容（支持递归）

smart_edit

自然语言指令编辑（调用 LLM 两步定位+操作）

Related MCP server: obsidian-mcp-server

特性

  • Bearer Token 鉴权 — HTTP 模式下强制 Token 验证，stdio 模式自动跳过

  • 路径安全 — 防止目录穿越，排除敏感目录（password、config 等）和指定文件

  • 冲突检测 — 写操作支持 expected_mtime 校验，防止多 Agent 基于过期内容误操作；写操作返回新 mtime 供后续使用

  • LLM 智能编辑 — smart_edit 通过 Kimi 大模型理解自然语言指令，两步执行：先定位目标内容，再精确操作

快速开始

环境准备

# Python 3.11+
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

配置

cp config/.env.example config/.env
# 编辑 config/.env，填入你的 API Key 和 Token

各字段说明见 config/.env.example。

启动

# stdio 模式（本地 Agent 直连，无需鉴权）
python mcp_server.py

# HTTP 模式（远程访问）
python mcp_server.py --transport http --port 8765

客户端连接

stdio 模式（推荐本地使用）：

Agent 客户端以子进程方式自动拉起 server，通过 stdin/stdout 管道通信，无需手动启动服务。

在 Claude Desktop、Cursor 等支持 MCP 的客户端中配置：

{
  "mcpServers": {
    "notes": {
      "command": "python",
      "args": ["/path/to/mcp_server.py"]
    }
  }
}

或在代码中使用 fastmcp Client：

from fastmcp import Client

async with Client("mcp_server.py") as client:
    result = await client.call_tool("list_notes", {"directory": ""})
    print(result[0].text)

更多示例见 tests/test_client_stdio.py。

HTTP 模式（远程访问）：

需要先手动启动服务，Agent 通过网络调用：

curl -X POST http://127.0.0.1:8765/mcp \
  -H "Authorization: Bearer your-secret-token" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

安全机制

  • 目录隔离：.venv、config、__pycache__、.git、password 目录不可访问

  • 文件黑名单：work/账号密码相关数据.md 等敏感文件被明确排除

  • 路径穿越防护：所有路径操作经过 resolve() 校验，禁止 .. 逃逸

  • Token 鉴权：HTTP 模式必须携带 Authorization: Bearer <token>

冲突检测机制

Agent A: read_note("file.md")     → 返回 mtime: 1751529600.123
Agent A: replace_in_note(..., expected_mtime=1751529600.123) → ✅ 成功，返回新 mtime: 1751529605.456
Agent B: replace_in_note(..., expected_mtime=1751529600.123) → ⚠️ 被拦截，提示重新读取

依赖

内网穿透（可选）

如需从公网访问，可自行搭建内网穿透。以 frp 为例：

  1. 下载 frpc 放到项目目录

  2. 配置 frpc.toml：

serverAddr = "your-server-ip"
serverPort = 9000

[[proxies]]
name = "mcp-server"
type = "tcp"
localIP = "127.0.0.1"
localPort = 8765
remotePort = 8765

  1. 启动时加 --frpc 自动拉起 frpc：

python mcp_server.py --transport http --port 8765 --frpc

也可手动单独启动 frpc，不依赖本服务管理。

License

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Notes MCP Server

    nathannj
    F
    license
    Not graded
    quality
    D
    maintenance
    Manages markdown notes in a specified directory, allowing users to create, read, update, and list notes through the Model Context Protocol.
    1
    -

  • obsidian-mcp-server

    indie-geeker
    A
    license
    B
    quality
    D
    maintenance
    Enables AI to manage Obsidian notes, including creation, reading, updating, deletion, full-text search, listing with filtering, sorting, and metadata extraction via the Model Context Protocol.
    8
    9 npm
    MIT

  • mor

    laat
    A
    license
    Not graded
    quality
    A
    maintenance
    Enables AI assistants to search, read, create, update, and remove personal markdown notes stored locally, providing persistent memory across sessions.
    60 npm
    2
    MIT

  • mcp-notes-server

    nadimhoss
    A
    license
    A
    quality
    B
    maintenance
    Provides an AI agent with a searchable markdown notes vault, offering tools to create, read, list, search, update, and delete notes stored as plain .md files.
    6
    MIT