Content
<p align="center">
<img src="./banner@2x.png" alt="mcp-standardnotes" width="100%">
</p>
# mcp-standardnotes
[](https://github.com/lozit/mcp-standardnotes/actions/workflows/ci.yml)
[](./LICENSE)
[](#requirements)
**Give Claude secure read/write access to your [Standard Notes](https://standardnotes.com/) vault — end-to-end encrypted, local stdio only, zero cloud middleman.**
Ask Claude to summarize your notes, draft new ones, organize tags, search across your vault — all while your master key stays on your machine. Works with Claude Code, Claude Desktop, and any MCP-compatible client.
> **Disclaimer.** This is an unofficial third-party integration. Not affiliated with, endorsed by, or sponsored by Standard Notes Ltd. "Standard Notes" is a trademark of Standard Notes Ltd.
## Why
- 🔒 **End-to-end encrypted.** All decryption happens locally using audited libsodium primitives (Argon2id + XChaCha20-Poly1305 IETF). Your password never leaves RAM; your master key never leaves your machine.
- 🔌 **Local stdio only.** No network port is ever opened by this server.
- 🔑 **OS keychain for session storage.** macOS Keychain, Linux libsecret, Windows Credential Vault — never plaintext files.
- ☁️ **Works with the official cloud or self-hosted** Standard Notes servers.
## Features
| Tool | What it does |
|------|---|
| `notes_list` / `notes_search` / `notes_get` | Browse and search your notes (filter by tag with `tag: "<uuid-or-title>"`) |
| `notes_create` / `notes_update` / `notes_delete` | Write notes (markdown, super, code, rich-text, task, spreadsheet, plain-text) |
| `notes_create_many` | Batch-create up to 50 notes in one sync push |
| `notes_stats` | Vault stats: counts, sizes, oldest/newest/largest note |
| `tags_list` / `tags_get` / `tags_create` / `tags_update` / `tags_delete` | Full tag CRUD |
| `tags_attach` / `tags_detach` | Link/unlink tags to notes |
| `sync` | Force a sync with the server |
`notes_create` and `notes_update` accept an optional `tags: string[]` (tag UUIDs) to link tags at write time.
## Requirements
- **Node.js ≥ 20**
- A Standard Notes account on **protocol 004** (default for any account created or upgraded since 2020)
- macOS, Linux, or Windows with a working OS keychain
## Quickstart
### 1. Install
```bash
npm install -g mcp-standardnotes
```
Or run from a clone if you prefer:
```bash
git clone https://github.com/lozit/mcp-standardnotes.git
cd mcp-standardnotes
npm install && npm run build
```
### 2. Log in once
```bash
mcp-standardnotes-login # if installed globally
# or, from a clone:
npm run login
```
You'll be prompted for email and password. The password derives your master key in memory (Argon2id) and is never written to disk. An encrypted session is stored in your OS keychain; subsequent runs reuse it automatically. At the end of `login`, you're offered to wire the server into Claude Desktop in one step — accept it, restart Desktop, done.
### 3. Hook it up to Claude
**Claude Desktop (macOS / Windows)** — easiest path, run:
```bash
mcp-standardnotes-install
```
This writes the right entry (absolute Node + binary paths, your email from the keychain) into `~/Library/Application Support/Claude/claude_desktop_config.json` (or `%APPDATA%/Claude/claude_desktop_config.json` on Windows), backing up any existing config first. Quit Claude Desktop fully (⌘Q) and relaunch.
**Claude Code** — let the `claude` CLI do it:
```bash
mcp-standardnotes-install code # prints the exact `claude mcp add` command
```
Or add to `~/.claude.json` / `.mcp.json` manually:
```json
{
"mcpServers": {
"mcp-standardnotes": {
"type": "stdio",
"command": "mcp-standardnotes",
"env": { "SN_EMAIL": "you@example.com" }
}
}
}
```
Then `/mcp` to reconnect.
**Any other MCP client** — run `node dist/index.js` with `SN_EMAIL` set in the environment. Transport is stdio.
**Self-hosting Standard Notes?** See [docs/self-hosted.md](./docs/self-hosted.md) for the docker-compose recipe and how to pin your TLS certificate.
## Configuration
| Variable | Default | Description |
|---|---|---|
| `SN_EMAIL` | *required* | Your SN account email. Must match what you used with `npm run login`. |
| `SN_SERVER_URL` | `https://api.standardnotes.com` | Sync server URL. Change for self-hosted instances. |
| `KEYCHAIN_SERVICE` | `mcp-standardnotes` | Override the keychain service name (useful for multiple accounts). |
| `SN_CERT_FINGERPRINT` | *unset* | SHA-256 TLS cert pin for self-hosted servers (64 hex chars, colons optional). See [docs/self-hosted.md](./docs/self-hosted.md). |
## Security at a glance
- Password in RAM only during key derivation. Never logged, never stored.
- Session + master key hex → OS keychain only. Never plaintext files.
- stdio transport only. No HTTP port, ever.
- All logs go to stderr, routed through a redactor that masks passwords, keys, JWTs, and token-like strings.
- All tool inputs validated by zod.
- `npm audit` HIGH/CRITICAL is a merge blocker in CI.
- Only the protocol 004 *framing* is implemented locally; all cryptographic primitives come from `libsodium-wrappers-sumo`.
Full threat model and deep-dive: [docs/protocol-004.md](./docs/protocol-004.md).
Security policy, vulnerability reporting, and dependency-advisory notes: [SECURITY.md](./SECURITY.md).
## Troubleshooting
Common issues and fixes: [docs/troubleshooting.md](./docs/troubleshooting.md).
## Logout
```bash
SN_EMAIL=you@example.com mcp-standardnotes-logout
# or, from a clone:
SN_EMAIL=you@example.com npm run logout
```
## Roadmap
Upcoming work tracked in [ROADMAP.md](./ROADMAP.md).
## Contributing
Contributions welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup, tests, and PR checklist.
## License
[MIT](./LICENSE) — use it, fork it, ship it.
## Credits
- [Standard Notes](https://standardnotes.com/) for the encryption design and public API.
- [Model Context Protocol](https://modelcontextprotocol.io) and [Anthropic](https://www.anthropic.com) for the MCP SDK.
- [libsodium](https://doc.libsodium.org/) by Frank Denis, exposed via [libsodium-wrappers-sumo](https://github.com/jedisct1/libsodium.js).
