notation MCPサーバー
コミット 2026年11月6日ネイティブなMCPエンドポイントを介して、AIクライアントがノートの読み取り、書き込み、ナビゲーションを行える、セルフホスト型のノートおよびファイルワークスペースです。
別名 atomfritte/notation
- スター
- 0
- ツール
- 16
- ダウンロード数(30日間)
- —
- 最新バージョン
- —
- 最終コミット
- 2026年11月6日
- ライセンス
- MIT
notation MCPとは
ネイティブなMCPエンドポイントを介して、AIクライアントがノートの読み取り、書き込み、ナビゲーションを行える、セルフホスト型のノートおよびファイルワークスペースです。 16個のツールを提供しており、list_files, get_tree, globなどがあります。
プロジェクトのREADMEから生成された概要
notation MCP server について
notationは、AIと統合されたワークスペースを通じて、個人の知識やファイルを管理することを開発者や研究者に提供します。このセルフホスト型ソリューションは単一のDockerコンテナで動作し、フラットファイルストレージを使用することで、データの完全な所有権を維持できるように設計されています。また、ネイティブなModel Context Protocolエンドポイントを提供しており、Claude CodeやCursorなどのクライアントが、read_file、write_file、grep、git_logといったツールを使用してノートと直接やり取りできます。
ユーザーは情報を個別のSpaceに整理でき、各Spaceは独自のGitバージョン管理リポジトリとして機能するため、履歴の追跡や復元が容易です。システムはMarkdown、PDF、スプレッドシートを含むさまざまなファイル形式をサポートしており、機密性の高いワークスペース向けにゼロ知識暗号化も提供しています。認証はpasskeysとWebAuthnを介して行われ、Magic-Linksを使用することで、特定の権限を持った制御された共有が可能です。ローカル環境でもリモートデプロイでも、人間による編集とAIによる自動支援の両方に適した構造化された環境を提供します。
できること
- 1ノート編集の自動化AIクライアントはMCPエンドポイントを使用して、ワークスペース内を検索し、Markdownファイルを直接修正できます。
- 2バージョン管理されたドキュメント組み込みのGit統合を使用して、ノートの変更履歴を追跡し、以前のバージョンに復元できます。
- 3暗号化されたプライベートワークスペースサーバーに届く前にブラウザ上で暗号化を行うことで、極めて機密性の高い情報を保護できます。
プロジェクトの README から作成されています。すべてのユースケースは、その引用と照らし合わせて確認されています。
notation MCPツール 16
READMEから検出list_filesget_treegloboutlinemapread_filewrite_filecreate_filedelete_filerename_filemkdirsearch
| list_files | — | |
| get_tree | — | |
| glob | — | |
| outline | — | |
| map | — | |
| read_file | — | |
| write_file | — | |
| create_file | — | |
| delete_file | — | |
| rename_file | — | |
| mkdir | — | |
| search | — |
16個のツールをすべて表示ツールを折りたたむ
grepgit_loggit_diffforms_guide
| grep | — | |
| git_log | — | |
| git_diff | — | |
| forms_guide | — |
設定
NOTATION_DATA_DIR
| 名前 | 説明 | 種類 |
|---|---|---|
| NOTATION_DATA_DIR | — |
自動チェック
実行日 2026年11月14日完全なレポート →まだ検証されていません。サーバーには80点のスコア、重大な問題がないこと、および検証に必要な十分なデータが必要です。 チェックの仕組み · 点数を上げるための改善点
- ソースリポジトリがリンクされており、アクセス可能atomfritte/notation is public and reachablegithub.com/atomfritte/notation ↗合格
- パッケージがこのリポジトリをソースとして指定未チェック
- ビルドの来歴 (Sigstore 証明)未チェック
- オープンソースライセンス (OSI)MITspdx.org/licenses/MIT.html ↗合格
- 過去1年以内にコミットまたはリリースありLast commit or release 2026-11-06github.com/atomfritte/notation ↗合格
- OpenSSF Scorecard未チェック
- パッケージ名が有名なパッケージに酷似していない未チェック
- パッケージおよびその依存関係に重大な勧告なし未チェック
- モデルへの隠れた指示がない16 tool descriptions and the README read; no override phrases, credential paths or hidden characters合格
- 破壊的なツールがラベル付けされている未チェック
- リモートエンドポイントが MCP ハンドシェイクに応答未チェック
README
GitHubで見るnotation
A self-hosted, single-container notes & file workspace with flat-file storage, per-Space Git history, Magic-Link sharing, passkey auth, and a native Model Context Protocol server for Claude Code / Cursor.
Why notation?
Most note tools force you to pick a side: either a SaaS that owns your data, or a self-hosted thing that's a pain to back up. notation keeps everything in plain files under a Docker volume, versions every Space with git, lets you share individual workspaces with permissions, and exposes a Model Context Protocol endpoint so Claude Code (or Cursor, or any MCP-speaking client) can edit your notes directly — all behind a single binary.
┌───────────────────────┐ ┌──────────────────────────┐
│ Browser (admin SPA) │ │ Claude Code / Cursor │
│ Magic-link visitors │ │ (MCP over HTTP+JSON-RPC)│
└──────────┬────────────┘ └────────────┬─────────────┘
│ │
└──────────────┬───────────────┘
▼
┌──────────────────────┐
│ notation container │
│ Go 1.24 + Vite SPA │
└──────────┬───────────┘
▼
/data/spaces/<id>/
├── files/ ← user content (git-versioned)
│ └── .git/
└── .notation/ ← shares.json, mcp-tokens.json,
comments.jsonl, audit.log,
admin.json, server-secret
Table of contents
- Features
- Quick start
- Configuration
- Authentication
- Spaces & Git versioning
- Magic Links
- Local folder sync
- Claude assistant
- MCP integration
- Supported file types
- Markdown features
- Zero-knowledge encryption
- Themes
- Keyboard shortcuts
- Security
- Backup & recovery
- Development
- Architecture
- License
Features
🗂️ Spaces
Each Space is a folder on disk with its own git repo. Auto-commit on save, manual snapshots, restore any past version side-by-side via Monaco diff editor.
✍️ Notion-grade editor
Monaco-based Markdown editor with toolbar, [[wiki-link]] picker, custom context menu, line numbers, selection toolbar, and a Cmd/Ctrl + K command palette that finds any page or action by name. Page tools sit in the header's More menu, Space tools and administration in the Space menu next to its name — grouped and labelled, as bottom sheets on a phone.
🔗 Magic Links
Share a Space with read, comment or edit permission. Optional expiry. Tokens hashed at rest, rate-limited, audit-logged.
🔑 Passkey auth
WebAuthn-first sign-in. Bootstrap token printed to stderr on first boot, single-use claim, then passkeys take over. Optional Authelia mode.
🧠 MCP server
Native HTTP MCP endpoint per Space. Bearer-token auth. Ships with read_file, write_file, grep, glob, outline, git_log, … so Claude can navigate intelligently.
📊 Universal viewer
Markdown, code (syntax-highlighted), images, PDF, video, audio, XLSX, DOCX, CSV — all in-browser, lazy-loaded, sanitised.
💬 Anchored comments & reactions
Select text → pin a comment or an emoji reaction to that exact quote. Annotated passages carry a visible badge; hover one to read the thread and reply without leaving the page.
🛡️ Hardened by default
os.Root sandbox, strict CSP, rehype-sanitize, CSRF tokens, per-IP rate limits, audit log with hash-chain integrity.
🔒 Zero-knowledge encryption
Encrypt a Space end-to-end in your browser: the server keeps ciphertext and opaque ids — not your contents, not even the file names. Per Space, reversible, with a one-time recovery key.
📂 Local folder sync
Pull a Space into a real folder, work on it with local tools or a coding agent, push the changes back through a reviewed 3-way diff. Works for plaintext and encrypted Spaces alike.
✨ Claude assistant
A chat panel next to every page: Claude reads, searches and edits the Space with your own API key — every change shown as a diff to accept or reject, with undo. Runs in the browser, so it works on encrypted Spaces too; chats persist per Space, sealed with the Space key when the Space is encrypted.
Quick start
Docker (one-liner)
docker run -d --name notation \
-p 8080:8080 \
-v $PWD/notation-data:/data \
-e NOTATION_BASE_URL="https://notes.example.com" \
ghcr.io/atomfritte/notation:latest # or: build the image locally
Watch the logs for the bootstrap token banner, then open the URL in your browser:
docker logs notation
═══════════════════════════════════════════════════════════════════
🔑 notation — admin bootstrap token (one-time, rotates per boot)
═══════════════════════════════════════════════════════════════════
Sw7Yk2-Bf3pQ8x_Lm9R4tHnGc6vAj1eUoZ_5KdMyXbN
Open https://notes.example.com and paste the token to claim the
admin account. Once you register a passkey, future restarts won't
print a token.
═══════════════════════════════════════════════════════════════════
Paste it on the Claim screen → register a passkey → you're in.
Docker Compose
services:
notation:
image: ghcr.io/atomfritte/notation:latest
restart: unless-stopped
ports:
- "8080:8080"
volumes:
- ./notation-data:/data
environment:
NOTATION_BASE_URL: "https://notes.example.com"
NOTATION_TRUST_PROXY: "1" # set if behind Traefik/Caddy/nginx
Build from source
git clone https://github.com/atomfritte/notation.git
cd notation
docker build -t notation:local .
docker run -d --name notation -p 8080:8080 -v $PWD/data:/data notation:local
Updating (Compose)
For the docker-compose.yml deployment (app + optional Kokoro voice sidecar),
scripts/update.sh recompiles and restarts the containers from source:
./scripts/update.sh # git pull, rebuild image(s), recreate containers
./scripts/update.sh notation # only the app (skip the kokoro sidecar)
./scripts/update.sh --no-cache # force a clean rebuild
./scripts/update.sh --no-pull # rebuild the current checkout
The frontend and Go binary are compiled inside the Dockerfile, so a rebuild is a
full recompile. Your data volume and the downloaded Kokoro model
(./kokoro-models) are left untouched.
Configuration
All configuration is via environment variables. None are required for a basic local run.
Core
| Variable | Default | Description |
|---|---|---|
NOTATION_BIND |
:8080 |
Listen address. |
NOTATION_DATA_DIR |
/data |
Where Spaces, auth records, audit logs live. Mount as a volume. |
NOTATION_BASE_URL |
(empty) | Public URL of the deployment. Used for share URLs, derives the WebAuthn rp_id, and tells the server when to mark cookies Secure. |
NOTATION_COOKIE_SECURE |
(empty) | Override the session cookie's Secure flag: 1 = always, 0 = never (plain-HTTP LAN). Unset: Secure unless NOTATION_BASE_URL starts with http:// — fail-safe for TLS-proxy setups that never set a base URL. |
NOTATION_MAX_UPLOAD_BYTES |
67108864 (64 MiB) |
Per-file upload limit. |
NOTATION_COMMIT_DEBOUNCE_MS |
5000 |
Window during which subsequent saves coalesce into one git commit. |
Routing
| Variable | Default | Description |
|---|---|---|
NOTATION_SHARE_PATH |
/s |
URL prefix for the Magic-Link app + assets. Must be Authelia-bypassed if you put Authelia in front. |
NOTATION_MCP_PATH |
/mcp |
URL prefix for the MCP HTTP endpoints. Also Authelia-bypass. |
Authentication
| Variable | Default | Description |
|---|---|---|
NOTATION_AUTH_MODE |
session |
One of session (notation's own passkey + cookie auth), authelia (trust Remote-User), or both (defense-in-depth). |
NOTATION_RP_ID |
derived from NOTATION_BASE_URL |
WebAuthn relying-party id (the bare host). Passkeys are bound to this — changing it invalidates all registered credentials. |
NOTATION_SESSION_LIFETIME_HOURS |
720 |
Session cookie lifetime in hours (default 30 days). |
NOTATION_TRUST_PROXY |
0 |
Set to 1 when behind a header-rewriting reverse proxy; otherwise X-Forwarded-For is ignored to prevent IP spoofing. |
NOTATION_ADMIN_HEADER |
Remote-User |
Authelia header name. Only used when AUTH_MODE includes authelia. |
NOTATION_ADMIN_GROUPS_HEADER |
Remote-Groups |
Authelia groups header. |
NOTATION_ADMIN_GROUP |
(empty) | If set, the user must be a member of this group. |
NOTATION_DEV_BYPASS_AUTH |
0 |
Do NOT set in production. Bypasses all auth, intended only for local Vite-against-backend development. |
Claude assistant
| Variable | Default | Description |
|---|---|---|
NOTATION_ANTHROPIC_API_KEY |
(empty) | Claude API key for the assistant. Optional: the key is normally entered in the app, where the browser encrypts it under a chat password before storing it (<data>/.notation/ai.json holds only the sealed copy). When set, it wins, needs no chat password, and the in-app key settings are read-only. |
NOTATION_AI_DISABLED |
0 |
Set to 1 to remove the assistant entirely (its endpoints answer 404 and the UI hides it). |
Behind a reverse proxy
notation works fine standalone, but a typical deployment puts it behind Traefik / Caddy / nginx for TLS termination.
# Traefik labels — adjust the hostname
labels:
- "traefik.enable=true"
- "traefik.http.routers.notation.rule=Host(`notes.example.com`)"
- "traefik.http.routers.notation.entrypoints=websecure"
- "traefik.http.routers.notation.tls.certresolver=le"
- "traefik.http.services.notation.loadbalancer.server.port=8080"
If you keep Authelia (perimeter SSO) and want notation's own session layer, set NOTATION_AUTH_MODE=both. The Magic-Link path (/s/*) and MCP path (/mcp/*) must always bypass Authelia — they have their own token auth.
Authentication
notation runs through a small state machine on every page load:
stateDiagram-v2
[*] --> NoAdmin: fresh /data
NoAdmin --> Claim: state.needs_claim
Claim --> PasskeySetup: bootstrap token verified, session issued
PasskeySetup --> Ready: 1+ passkey registered
Ready --> Login: session expired
Login --> Active: WebAuthn assertion verified
Active --> Ready: logout / expire
Active --> [*]: app
Bootstrap
- On every boot, if no admin is yet claimed, a 32-byte random token is generated, hashed (SHA-256) and printed to stderr in a banner.
- The token rotates on every restart until claimed, so the most recent container log always shows the live one.
- Claim is rate-limited: 10 failures per IP locks for 1 hour. Constant-time hash compare.
Passkeys (WebAuthn)
- Powered by
go-webauthn(server) and@simplewebauthn/browser(client). - Discoverable-credential flow: the browser shows the system passkey picker. No usernames, no passwords.
- Multiple passkeys per admin. You cannot delete the last one (would lock you out).
- Sessions are HMAC-signed cookies (
HttpOnly,Secure,SameSite=Strict), 30-day sliding window. CSRF token lives inside the cookie payload and is verified via theX-CSRF-Tokenheader.
Lost passkey recovery
docker exec -it notation rm /data/.notation/admin.json
docker restart notation
docker logs notation # ← new bootstrap token in the banner
Spaces, Magic Links, MCP tokens, and audit logs are untouched.
Spaces & Git versioning
A Space is a folder under /data/spaces/<id>/. The structure is intentionally simple:
/data/spaces/<id>/
├── files/ ← everything users see
│ ├── .git/
│ ├── note.md
│ └── attachments/
│ └── pic.png
└── .notation/ ← server-side metadata
├── meta.json
├── shares.json (hashed)
├── mcp-tokens.json (hashed)
├── comments.jsonl
└── audit.log (hash-chained)
- Auto-commit on save with a 5-second debounce window. Subsequent edits within the window become one commit.
- The git repo lives inside
files/so.notation/(secrets, audit) never enter version history. - The author of each commit identifies the source:
admin:<name>/guest:<share-id>/mcp:<token-id>. - Per-file history viewer in the admin UI: pick two commits, see a Monaco side-by-side diff; pick one, get a single-click Restore.
Magic Links
Click the Sharing tab in any Space → create a link with a permission level, an optional scope (a single page or folder), and optional expiry.
| Permission | Can read | Can comment | Can edit |
|---|---|---|---|
read |
✅ | — | — |
comment |
✅ | ✅ | — |
edit |
✅ | ✅ | ✅ |
- Scoped links: leave the scope empty to share the whole Space, or set it to a page (
notes/weekly.md) or folder (notes/). Guests only ever see that subtree — tree, file access, search, comments and forms are all enforced server-side against the scope; requests outside it get a 403 and an audit entry. A page that embeds attachments from outside its scope will show them blocked — share the folder instead. - Tokens are 32 random bytes (base64url, ~43 chars), only their SHA-256 hash is persisted.
- Constant-time lookup across Spaces.
- Path
<NOTATION_SHARE_PATH>/<token>— Authelia-bypassed. - Per-IP rate limit (5 rps avg, 20 burst).
- Every action is appended to the Space's
audit.logwith the actorshare:<id>:<perm>.
The viewer at the share URL is the same React app as the admin's, in read-only / comment / edit mode depending on permission. Visitors get the same Markdown viewer (Mermaid, KaTeX, syntax highlight), file-type previews, anchored comments, threaded replies.
Local folder sync
Work on a Space with local tools — an editor, a script, a coding agent — and bring the result back under review. Open a Space → Local folder sync (the header's folder icon, or the file-tree context menu), pick a directory, and you get two explicit actions. There is no live auto-sync: nothing moves without a click.
| Action | What it does |
|---|---|
| Pull | Writes every file of the Space into the folder, recreating the tree (empty folders included). Files already in the folder that the Space doesn't know about (a .git, scratch files) are left alone. |
| Push | Reads the folder back, diffs it, shows a change preview (new / modified / moved / deleted / conflict) and applies it only when you confirm. Deletions are opt-in via a separate checkbox. |
- Works for every Space — plaintext or zero-knowledge encrypted. For an encrypted Space the browser decrypts on pull and re-encrypts on push; the server never sees anything but ciphertext. The panel says so plainly, because pull does write decrypted files to your disk.
- A plaintext Space's push is an ordinary write, so every pushed file lands in the Space's git history like any other edit.
- The folder briefs your agent — with what the in-app assistant gets. Every pull writes
.claude/rules/notation-space.md: the same briefing the assistant works from (what a notation Space is, what renders, Forms, comment anchors, theCHANGELOG.mdentry every change needs, how the push treats what it finds) plus your assistant instructions for every Space. Claude Code loads it at every start, whicheverCLAUDE.md/AGENTS.mdthe Space has. Every skill the assistant offers — the Space's own and the skill library's — is mirrored into.claude/skills/<name>/, so/nameworks in Claude Code too. When the Space has noAGENTS.md, a short one points other agents (Cursor, Codex, …) at the briefing. NoCLAUDE.mdis generated: it would stop Claude Code from reading the Space'sAGENTS.mdfiles. All of it is tooling, not content:.claude/never syncs, the push strips a generatedAGENTS.mdback out, a file of the Space's own always keeps its name, and deleting the marker line turns a generated file into ordinary content. - A rename is a move, not a delete + create. A folder can only report "this path is gone, that one appeared". The push pairs the two back up — by identical content, or by an unchanged filename when the file was edited on the way — and asks the Space for a real move. That is what keeps a relocated page's comments, reactions and git history attached instead of stranding every annotation on it. Moves are listed with both paths in the preview and don't need the deletions checkbox: nothing is being removed.
- 3-way diff, not last-writer-wins. A
.notation-sync.jsonmanifest (path → content hash) is written into the folder at every successful sync. It's what separates "the folder added a file" from "the Space deleted one", and it flags a real conflict when both sides changed the same file since the last sync (resolution is folder-wins, and every conflict is listed before you confirm). - Ignored on both sides: dotfiles and dot-directories (
.git,.env, the manifest itself) and anynode_modules/. - A failed write doesn't poison the baseline. If the server rejects a file (too large, connection lost), the push still applies everything else, reports what failed, and keeps those paths out of the sync record so the next push retries them.
- Requirements: a Chromium-based browser (Chrome, Edge, Brave) over https or localhost — it uses the File System Access API. The picked folder is remembered per Space in IndexedDB; you only re-grant permission with one click. No encryption key is ever stored there.
Claude assistant
A chat panel on the right of every Space (the ✨ button in the header, or Alt + A). Ask about the pages, or have Claude write, restructure and tidy them — the way you would with a coding agent after a folder sync, without leaving the app.
- Bring your own key, sealed with a chat password. Add a Claude API key once in the panel, together with a chat password (or set
NOTATION_ANTHROPIC_API_KEY); usage is billed to that key. The browser encrypts the key (Argon2id → AES-256-GCM) before it is stored, so the server — and its disk and backups — only ever hold a sealed copy. Enter the password once per tab to unlock; Lock (or a reload, or signing out) forgets the key again. Forgot the password? Replace key… in the settings. A plaintext key stored by an older version is sealed the next time you open the panel. - Pick the model. The model pill under the message box lists every model your key can use (live from the Models API, with prices for the ones notation knows) and how much effort Claude spends; Use for new chats makes the pick the default. The panel shows an estimated cost and the current context size.
- You approve every change. Writes, edits, moves and deletes are shown as a diff first — Apply, Reject (optionally telling Claude what to do instead), or Apply all in this chat. An Auto-apply switch skips the question; every applied change keeps an Undo button, which refuses to overwrite edits made after it. A page open in the editor with unsaved changes is never touched.
- Works on encrypted Spaces. The whole agent loop runs in your browser tab: it talks to the Claude API directly and reads/writes the Space through the same interface as the folder sync — the decrypted, in-browser file system for an encrypted Space. The notation server is not in the conversation path.
- Chats persist per Space, across sessions and devices, in
<space>/.notation/chats/(plaintext Space) or sealed with the Space key (encrypted Space — AES-GCM, each record bound to its chat id and role). The server refuses plaintext chat records on an encrypted Space, and encrypting/decrypting a Space re-seals or unseals its chats as part of the conversion. - Space instructions and skills, by Claude Code's rules. The assistant loads a Space's
CLAUDE.mdandCLAUDE.local.md— orAGENTS.mdwhen there is neither — with@pathimports (four hops), comments stripped and Claude Code's size cap; a folder's ownCLAUDE.md(orAGENTS.md) joins the first time Claude touches a file there. EverySKILL.md(e.g.skills/protokoll/SKILL.md) is a skill with Claude Code's frontmatter (description,when_to_use,disable-model-invocation,user-invocable,paths,arguments); type/name argsto run one yourself. A skill library Space (settings) adds skills to every chat and wins a name clash, like personal skills. A folder sync gives Claude Code the same set, so a Space is worked on the same way in both. - Traceable. Claude appends one entry per request to
CHANGELOG.md. On a plaintext Space each change is a git commit byai:<you>.
What leaves the box. What Claude reads to answer you — pages, search hits — is sent to Anthropic's API under your key (API data isn't used for model training). Nothing else: the sealed key is handed to the signed-in admin's tab only (CSRF-protected), unlocked there with the chat password into memory (never browser storage); Magic-Link guests and MCP tokens can't reach it or the chats. Page content is treated as untrusted input (a page can't instruct Claude to act), and no change happens without the approval flow above.
MCP integration
Each Space exposes an HTTP+JSON-RPC Model Context Protocol endpoint at <NOTATION_MCP_PATH>/<space-id>. Auth is Authorization: Bearer <token>. Tokens are scoped to one Space.
Adding to Claude Code
claude mcp add notation-myspace "https://notes.example.com/mcp/myspace" \
--transport http \
--scope project \
--header "Authorization: Bearer <token>"
Or paste into .mcp.json:
{
"mcpServers": {
"notation-myspace": {
"type": "http",
"url": "https://notes.example.com/mcp/myspace",
"headers": { "Authorization": "Bearer <token>" }
}
}
}
Adding to Cursor
~/.cursor/mcp.json (global) or .cursor/mcp.json (project):
{
"mcpServers": {
"notation-myspace": {
"url": "https://notes.example.com/mcp/myspace",
"headers": { "Authorization": "Bearer <token>" }
}
}
}
notation MCPのよくある質問
notation MCPが提供するツールは
16個のツールを提供しており、list_files, get_tree, glob, outline, mapなどがあります。
ClaudeやCursorでノートを直接編集できますか?
はい。このサーバーはネイティブなModel Context Protocolエンドポイントを公開しており、AIクライアントがノートをナビゲートして編集することを可能にします。
データの保存方法とバージョン管理はどうなっていますか?
データはDockerボリューム内のプレーンファイルとして保存されます。また、各SpaceはGitを使用してバージョン管理されており、保存時に自動コミットが行われます。
エンドツーエンド暗号化はサポートされていますか?
はい。ブラウザ上でSpaceをエンドツーエンドで暗号化できるため、サーバー側からは暗号文と不透明なIDのみが見える状態になります。
ブラウザで閲覧できるファイル形式は何ですか?
ユニバーサルビューアーにより、Markdown、コード、画像、PDF、動画、音声、XLSX、DOCX、CSVをサポートしています。