CipherNote MCP
CipherNote MCP lets you securely manage local encrypted notes through MCP tools.
Create encrypted notes with title, content, optional tags, and importance.
Search notes locally by keyword with a configurable result limit.
Read a full note by its ID.
List recent note metadata without returning note bodies.
Permanently delete a note by its ID.
Designed for private note storage; do not use it for passwords, tokens, or other credentials.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@CipherNote MCP save a private note titled 'Grocery ideas' with my meal prep plan"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
🔐 CipherNote MCP
一个本地优先、加密存储的 MCP 私人笔记本
让支持 MCP 的 AI 客户端安全地保存、检索和管理长期笔记。
✨ 功能特点
功能 | 说明 |
🔒 加密存储 | 标题、正文和标签在写入 SQLite 前使用 AES-256-GCM 加密 |
🏠 本地优先 | 不包含云同步、遥测、分析或任何远程 API 请求 |
🔎 本地搜索 | 笔记仅在本机内存中解密和搜索 |
🧩 MCP 支持 | 支持本地 stdio 和远程 Streamable HTTP |
🌐 安全远程访问 | 内置 Bearer 鉴权、Host 校验和可选 TLS |
🛡️ 凭据拦截 | 自动拒绝疑似密码、令牌、私钥等敏感凭据 |
📦 轻量部署 | Node.js 负责 MCP 通信,Python 负责加密存储 |
Related MCP server: agent-notes-mcp
🧰 MCP 工具
CipherNote 提供以下五个工具:
工具 | 用途 |
| 创建加密笔记 |
| 根据关键词搜索笔记 |
| 根据笔记 ID 读取完整内容 |
| 查看最近笔记的元数据,不返回正文 |
| 永久删除指定笔记 |
🚀 快速开始
1. 环境要求
Node.js 20 或更高版本
Python 3.10 或更高版本
系统命令行中可以使用
python;Linux/macOS 默认也支持python3
2. 下载并安装
git clone https://github.com/xuns1919-ux/ciphernote-mcp.git
cd ciphernote-mcp
npm install
python -m venv .venv激活虚拟环境:
# Windows PowerShell
.venv\Scripts\Activate.ps1
# Linux / macOS
source .venv/bin/activate安装 Python 依赖:
python -m pip install -r requirements.txt3. 生成加密密钥
python scripts/generate_key.py命令会输出类似下面的内容:
CIPHERNOTE_KEY=base64:YOUR_RANDOM_KEY请把密钥保存在密码管理器或客户端的安全存储中。不要将真实密钥写入 Git,也不要与数据库放在同一个备份位置。
4. 配置 MCP 客户端
将下面配置中的项目路径和密钥替换为你自己的值:
{
"mcpServers": {
"ciphernote": {
"command": "node",
"args": ["/absolute/path/to/ciphernote-mcp/src/server.js"],
"env": {
"CIPHERNOTE_KEY": "base64:YOUR_RANDOM_KEY"
}
}
}
}建议通过客户端提供的密钥管理功能传入 CIPHERNOTE_KEY,不要直接把真实密钥写进会被同步或提交的配置文件。
5. 运行服务
npm start默认模式继续使用标准输入输出(stdio)与 MCP 客户端通信。协议消息写入标准输出,诊断信息写入标准错误。
🌐 Streamable HTTP
v0.2.0 起可以直接提供原生 Streamable HTTP,无需额外 wrapper。HTTP 模式始终要求至少
32 字符的 Bearer Token;缺少或错误的 Token 返回 401 Unauthorized。
生成 Token 并限制文件权限:
umask 077
openssl rand -hex 32 > /etc/ciphernote-mcp/token推荐在 Nginx、Caddy 等 TLS 反向代理后仅监听回环地址:
export CIPHERNOTE_TRANSPORT=http
export CIPHERNOTE_HOST=127.0.0.1
export CIPHERNOTE_PORT=18060
export CIPHERNOTE_HTTP_PATH=/mcp
export CIPHERNOTE_AUTH_TOKEN_FILE=/etc/ciphernote-mcp/token
export CIPHERNOTE_ALLOWED_HOSTS=notes.example.com
npm start客户端连接 https://notes.example.com/mcp,传输方式选择 Streamable HTTP,并发送:
Authorization: Bearer YOUR_TOKEN反向代理必须保留 Authorization 请求头,并关闭响应缓冲。Nginx 示例:
location = /mcp {
proxy_pass http://127.0.0.1:18060/mcp;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header Authorization $http_authorization;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_buffering off;
proxy_request_buffering off;
proxy_read_timeout 3600s;
}也可以由 CipherNote 直接终止 TLS,此时证书和私钥必须同时设置:
export CIPHERNOTE_TRANSPORT=http
export CIPHERNOTE_HOST=0.0.0.0
export CIPHERNOTE_PORT=8443
export CIPHERNOTE_AUTH_TOKEN_FILE=/etc/ciphernote-mcp/token
export CIPHERNOTE_ALLOWED_HOSTS=notes.example.com
export CIPHERNOTE_TLS_CERT=/etc/letsencrypt/live/notes.example.com/fullchain.pem
export CIPHERNOTE_TLS_KEY=/etc/letsencrypt/live/notes.example.com/privkey.pem
npm start非回环监听如果没有 TLS 或没有显式的允许 Host 列表,服务会拒绝启动。生产环境只应开放
HTTPS 端口,不要将未加密的后端端口暴露到公网。GET /healthz 是不含敏感信息的健康检查。
⚙️ 环境变量
变量 | 必需 | 默认值 | 说明 |
| 是 | 无 | 32 字节密钥,必须使用 |
| 否 | 系统本地数据目录 | 自定义 SQLite 数据库路径 |
| 否 | Windows 使用 | 自定义 Python 可执行文件 |
| 否 |
|
|
| HTTP |
| HTTP 监听地址 |
| HTTP |
| HTTP 监听端口 |
| HTTP |
| Streamable HTTP 路径 |
| 二选一 | 无 | 至少 32 字符的 Bearer Token |
| 二选一 | 无 | 从受保护文件读取 Bearer Token |
| 远程 HTTP | 回环地址 | 逗号分隔的允许 Host 名称 |
| 可选 | 无 | PEM 证书链,必须和 TLS 私钥同时设置 |
| 可选 | 无 | PEM 私钥,必须和 TLS 证书同时设置 |
| 否 |
| HTTP 请求体限制,最大 10 MiB |
默认数据库位置:
Windows:
%LOCALAPPDATA%\ciphernote-mcp\ciphernote.dbLinux:
$XDG_DATA_HOME/ciphernote-mcp/ciphernote.db,未设置时使用~/.local/sharemacOS:默认与其他 Unix 系统一致,也可以通过
CIPHERNOTE_DB指定位置
🔐 隐私与安全模型
已加密的数据
笔记标题
笔记正文
标签
未隐藏的元数据
数据库文件大小
笔记数量和密文长度
笔记 ID
创建和更新时间
重要性等级
访问模式
CipherNote 主要保护被单独复制或泄露的数据库文件。它不能抵御以下情况:
攻击者已经控制运行 CipherNote 的设备
其他进程可以读取
CIPHERNOTE_KEY或检查进程内存MCP 客户端本身不可信
管理员权限、恶意软件或键盘记录器
CipherNote 不是密码管理器。请勿用它保存密码、API Key、Cookie、访问令牌、SSH 私钥或恢复码。
更多信息请阅读 安全策略。
💾 备份与恢复
请分别备份数据库和加密密钥。丢失密钥后,笔记内容无法恢复。
SQLite 运行时可能生成 -wal 和 -shm 文件。为了获得一致的备份,建议先停止 MCP 服务,再复制数据库;或者同时备份数据库及其 WAL 文件。
🗂️ 项目结构
ciphernote-mcp/
├── scripts/
│ └── generate_key.py # 安全生成随机密钥
├── src/
│ ├── server.js # stdio/HTTP 启动入口
│ ├── ciphernote.js # MCP server factory 和工具注册
│ ├── http.js # Streamable HTTP、TLS 和 Bearer 鉴权
│ └── store.py # 加密和 SQLite 存储层
├── tests/
│ ├── http.test.js # HTTP、鉴权、Host 和 MCP 集成测试
│ └── test_store.py # 存储、加密和凭据拦截测试
├── .env.example # 环境变量示例,不包含真实密钥
├── SECURITY.md # 安全策略与威胁模型
└── requirements.txt # Python 依赖🧪 开发与测试
python -m pip install -r requirements.txt
npm test
node --check src/server.js测试会使用临时数据库,不会读取你的真实笔记。
🤝 参与贡献
欢迎提交 Issue 和 Pull Request。提交代码前请确保:
没有包含真实笔记、数据库、密钥或个人信息。
所有测试均已通过。
新增安全相关功能时同步更新
SECURITY.md。
发现安全漏洞时,请不要在公开 Issue 中发布利用代码、真实密钥或笔记数据库。请使用 GitHub 的私密漏洞报告功能。
📄 开源许可
本项目使用 MIT License。
数据属于你,密钥也属于你。
Available Tools
5 toolsprivate_note_deleteC
Permanently delete one note by ID.
Inputs: note_id (required).
private_note_readC
Read one encrypted note by ID.
Inputs: note_id (required).
private_note_recentB
List recent note metadata without returning note bodies.
Inputs: limit.
private_note_searchC
Search encrypted notes locally.
Inputs: query (required), limit.
private_note_writeC
Write an encrypted local note. Do not use it for passwords, tokens, or other credentials.
Inputs: title (required), content (required), tags, importance.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a clearly distinct action: write creates a note, read retrieves one by ID, search queries notes, recent lists metadata, and delete removes a note. The search/recent distinction is explicitly clarified by recent returning metadata only, so there is little risk of misselection.
All tools consistently use the private_note_ prefix with snake_case suffixes, making the set easy to scan. The only minor deviation is that recent is an adjective rather than a verb, while the others follow an action-oriented pattern.
Five tools are well-scoped for a focused encrypted-notes server and each operation earns its place. The set avoids redundant listing or administrative tools that would bloat the surface.
The surface covers creation, retrieval, search, recent listing, and deletion, which supports most note workflows. However, there is no update/edit operation, forcing agents to delete and recreate notes to modify content, which is a notable lifecycle gap.
Maintenance
Related MCP Connectors
Persistent memory layer for AI tools. Save and recall notes across Claude and other MCP clients.
Google Keep-style notes app with an MCP server for AI agents to read/write notes.
Agent-native notes, tasks, dev-docs, vaults, sync & handoffs. MCP + OpenAPI dual surface.
MCP-native notes and memory for ChatGPT, Claude, and other AI tools.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA personal note store exposed as an MCP server. Enables any MCP-speaking assistant to create, search, list, and categorize notes, with per-client bearer tokens for author attribution.-
- AlicenseNot gradedqualityCmaintenanceLets MCP clients search, read, create, append, replace, move, and batch-update local Markdown notes safely, with conflict detection via SHA-256 and optional managed update blocks, without requiring a vector database.MIT
- AlicenseNot gradedqualityBmaintenanceEnables LLM clients to read, search, create, update, and delete notes in a self-hosted shared memory bank over MCP, using hybrid vector and full-text search with optional summarization.4MIT
- AlicenseNot gradedqualityCmaintenanceEnables MCP-compatible clients to create, list, search, and delete notes, read all notes as markdown, and use prompts to summarize or clean up notes.MIT