内容
# @voltanotes/mcp
[](https://www.npmjs.com/package/@voltanotes/mcp)
[](LICENSE)
用于 [Volta Notes](https://voltanotes.com) 的 MCP 服务器 - 从任何 AI 代理创建和读取 **阅后即焚** 的加密笔记。
笔记使用 **端到端加密** 的 AES-256-GCM 进行加密。解密密钥仅存储在 URL 片段中 - 永远不会发送到任何服务器。笔记存储在 [Internet Computer](https://internetcomputer.org) 上，并在单次读取后永久销毁。
## 为什么
AI 代理在运行时经常需要敏感信息 - API 密钥、密码、凭证。今天，用户将这些信息粘贴到聊天中，它们会永久存储在对话历史中。
使用此 MCP 服务器，模式变为：
1. 用户在 [voltanotes.com](https://app.voltanotes.com) 上创建笔记并发送一次性 URL
2. 代理调用 `read_volta_note` - 返回秘密，笔记永久销毁
3. 聊天历史中永远不会出现敏感信息
或者反之亦然 - 代理可以使用 `create_volta_note` 通过自毁链接向用户发送凭证。
## 快速开始
### Claude Code（CLI 和桌面应用）
**步骤 1 - 全局安装：**
```bash
npm install -g @voltanotes/mcp
```
**步骤 2 - 注册服务器：**
```bash
claude mcp add -s user volta -- node $(npm root -g)/@voltanotes/mcp/dist/index.js
```
就这样。重启 Claude Code 后，`create_volta_note` 和 `read_volta_note` 工具将可用。
> **为什么使用 `claude mcp add` 而不是编辑配置文件？** Claude Code 从其自己的注册表中读取 MCP 服务器，而不是从 `~/.claude/mcp.json` 中。使用 CLI 可以确保服务器正确注册。`-s user` 标志使其在所有项目中可用。
> **`node` 未找到？** 使用完整路径：替换 `node` 为 `which node` 的输出（例如 `/usr/local/bin/node`）。
### Claude 桌面版（独立版）
将以下内容添加到您的 `claude_desktop_config.json` 中：
```json
{
"mcpServers": {
"volta": {
"command": "npx",
"args": ["-y", "@voltanotes/mcp"]
}
}
}
```
### 其他 MCP 兼容客户端
上面的 `npx` 配置适用于任何支持标准 `command`/`args` MCP 格式的客户端 - 包括 **Cursor**、**Windsurf**、**Cline**、**Continue.dev** 等。查看您客户端的 MCP 文档，了解在哪里添加服务器配置。
### Hermes 代理（Nous Research）
Volta MCP 通过其 MCP 集成与 [Hermes 代理](https://hermes-agent.nousresearch.com) 配合使用。将服务器添加到您的 Hermes 配置中（`~/.hermes/config.yaml`）：
```yaml
mcp:
servers:
- name: volta
command: npx
args:
- "-y"
- "@voltanotes/mcp"
```
重启 Hermes 后，`create_volta_note` 和 `read_volta_note` 工具将可用于您的代理。
**代理到代理用例：** 独立运行的 Hermes 代理通常需要在工作流之间传递凭证，而不希望将其暴露在日志或内存中。Volta Notes 专门为此而设计 - 一个代理创建笔记，将一次性 URL 传递给下一个代理，秘密在读取时被销毁。没有任何内容保留在对话历史或工具输出日志中。
查看 [Hermes MCP 文档](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp) 以获取完整的配置选项。
### Windows（Claude Code CLI）
`$(npm root -g)` 语法在 PowerShell 或 CMD 中不起作用。请改用以下命令：
```bash
claude mcp add -s user volta -- node "%APPDATA%\npm\node_modules\@voltanotes\mcp\dist\index.js"
```
或者使用上面的 Claude Desktop / npx 方法，该方法适用于跨平台。
## 工具
### `create_volta_note`
创建加密笔记并返回一次性 URL。
| 参数 | 类型 | 描述 |
| --- | --- | --- |
| `content` | 字符串 | 要加密的秘密内容（最大 2 KB） |
**返回：** 一个 `voltanotes.com` URL。接收者打开它一次，读取内容，然后它就会永远消失。
### `read_volta_note`
读取并永久销毁 Volta 笔记。
| 参数 | 类型 | 描述 |
| --- | --- | --- |
| `url` | 字符串 | 完整的 Volta URL，包括 `#` 片段 |
**返回：** 解密的笔记内容。笔记从 canister 中永久删除 - 第二次读取将失败。
## 代理提示片段
将以下内容添加到任何代理的系统提示中，以启用安全的凭证传递：
```
当您需要来自用户的秘密（API 密钥、密码、凭证）时：
1. 要求他们前往 voltanotes.com 并在笔记字段中粘贴秘密
2. 他们将获得一次性 URL - 要求他们将其发送给您
3. 使用 read_volta_note 工具与该 URL 检索秘密
秘密在您读取后永久销毁 - 它永远不会出现在聊天历史中。
```
## 安全模型
- **AES-256-GCM** 加密在发送到 canister 之前在本地进行
- 加密密钥仅存在于 URL 片段（`#...`）中 - 浏览器和服务器永远不会传输片段
- ICP canister 仅存储密文 - 即使被泄露，所有数据也是不可读的
- 笔记在第一次读取时销毁。未读取的笔记在 7 天后过期。
- 没有帐户，没有登录，没有跟踪
## 工作原理
```
代理调用 create_volta_note("secret-api-key-123")
→ 本地：生成 AES-256 密钥 + 加密
→ ICP canister：存储密文 → 返回 noteId
→ 返回 URL：voltanotes.com/r/{noteId}#{key}
用户打开 URL → 读取门 → 点击“读取笔记”
→ 浏览器：从 canister 获取密文（canister 删除它）
→ 浏览器：使用 # 片段中的密钥解密
→ 显示明文 - 笔记永远消失
```
## 故障排除
### 检查服务器是否连接
```bash
claude mcp list
```
您应该看到 `volta: ... ✓ Connected`。如果没有，请参见下文。
### 服务器未显示
1. **您是否使用了 `claude mcp add`？** 手动编辑 `~/.claude/mcp.json` 不起作用 - Claude Code 从其自己的注册表中读取服务器。始终使用 `claude mcp add` 注册服务器。
2. **`node` 是否在您的 PATH 中？** Claude Code 的 shell 具有最小的 PATH。如果找不到 `node`，请使用完整路径：
```bash
claude mcp add -s user volta -- $(which node) $(npm root -g)/@voltanotes/mcp/dist/index.js
```
3. **需要重启。** 添加或更改 MCP 服务器后，请完全重启 Claude Code（退出并重新打开）。
### 如何知道服务器是否已启动？
服务器在成功启动时将 `Volta MCP server started` 记录到 stderr 中。运行 `claude mcp list` 以检查连接状态。
## 要求
- Node.js 18+（使用内置的 Web Crypto API）
## License
MIT - [Unprompted Labs](https://voltanotes.com)
