MCP server notation
Commit 6 de nov. de 2026Um workspace de notas e arquivos auto-hospedado que permite que clientes de IA leiam, escrevam e naveguem em suas notas por meio de um endpoint MCP nativo.
Também conhecido como atomfritte/notation
- Stars
- 0
- Ferramentas
- 16
- Downloads, 30 dias
- —
- Versão mais recente
- —
- Último commit
- 6 de nov. de 2026
- Licença
- MIT
O que é o MCP notation?
Um workspace de notas e arquivos auto-hospedado que permite que clientes de IA leiam, escrevam e naveguem em suas notas por meio de um endpoint MCP nativo. Ele expõe 16 ferramentas, como list_files, get_tree, glob.
Resumo gerado a partir do README do projeto
Sobre o MCP server de notation
Gerenciar conhecimento pessoal e arquivos por meio de um workspace integrado à IA é o que o notation possibilita para desenvolvedores e pesquisadores. Esta solução auto-hospedada roda em um único container Docker e utiliza armazenamento em arquivos simples para garantir que você mantenha total propriedade de seus dados. Ele fornece um endpoint nativo do Model Context Protocol que permite que clientes como Claude Code ou Cursor interajam diretamente com suas notas usando ferramentas como read_file, write_file, grep e git_log.
Os usuários podem organizar informações em Spaces distintos, cada um funcionando como seu próprio repositório versionado via git para facilitar o rastreamento de histórico e restauração. O sistema suporta vários tipos de arquivos, incluindo Markdown, PDF e planilhas, e oferece criptografia zero-knowledge para workspaces sensíveis. A autenticação é feita via passkeys e WebAuthn, enquanto Magic-Links permitem o compartilhamento controlado com permissões específicas. Esteja você trabalhando localmente ou via um deployment remoto, o servidor fornece um ambiente estruturado tanto para edição humana quanto para assistência automatizada de IA.
O que você pode fazer com ele
- 1Edição de notas automatizadaUm cliente de IA pode pesquisar em seu workspace e modificar arquivos markdown diretamente usando o endpoint MCP.
- 2Documentação com controle de versãoVocê pode rastrear alterações em suas notas e restaurar versões anteriores usando a integração git integrada.
- 3Workspaces privados criptografadosProteja informações altamente sensíveis criptografando-as no navegador antes que elas cheguem ao servidor.
Escrito a partir do README do projeto. Cada caso de uso é verificado com uma citação dele.
Ferramentas do MCP notation 16
Detectadas a partir do READMElist_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 | — |
Mostrar todas as 16 ferramentasMostrar menos ferramentas
grepgit_loggit_diffforms_guide
| grep | — | |
| git_log | — | |
| git_diff | — | |
| forms_guide | — |
Configuração
NOTATION_DATA_DIR
| Nome | Descrição | Tipo |
|---|---|---|
| NOTATION_DATA_DIR | — |
Verificações automatizadas
Executado em 14 de nov. de 2026Relatório completo →Ainda não verificado. Um servidor precisa de uma pontuação de 80, nenhum problema grave e dados suficientes para verificarmos. Como as verificações funcionam · O que corrigir para ganhar mais pontos
- Repositório de origem vinculado e acessívelatomfritte/notation is public and reachablegithub.com/atomfritte/notation ↗Passou
- O pacote indica este repositório como sua origemNão verificado
- Proveniência da build (atestação Sigstore)Não verificado
- Licença de código aberto (OSI)MITspdx.org/licenses/MIT.html ↗Passou
- Commit ou release no último anoLast commit or release 2026-11-06github.com/atomfritte/notation ↗Passou
- OpenSSF ScorecardNão verificado
- Nome do pacote não é próximo a um pacote popularNão verificado
- Nenhum aviso crítico no pacote ou em suas dependênciasNão verificado
- Sem instruções ocultas para o modelo16 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPassou
- Ferramentas destrutivas estão rotuladasNão verificado
- O endpoint remoto responde ao handshake do MCPNão verificado
README
Ver no GitHubnotation
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>" }
}
}
}
Perguntas sobre o MCP notation
Quais ferramentas o MCP notation oferece?
Ele expõe 16 ferramentas, incluindo list_files, get_tree, glob, outline, map.
O Claude ou o Cursor podem editar minhas notas diretamente?
Sim, o servidor expõe um endpoint nativo do Model Context Protocol que permite que clientes de IA naveguem e editem suas notas.
Como meus dados são armazenados e versionados?
Os dados são armazenados em arquivos simples sob um volume Docker, e cada Space é versionado usando Git com auto-commit ao salvar.
Ele suporta criptografia de ponta a ponta?
Sim, você pode criptografar um Space de ponta a ponta no seu navegador para que o servidor veja apenas o texto cifrado e IDs opacos.
Quais tipos de arquivos posso visualizar no navegador?
O visualizador universal suporta Markdown, código, imagens, PDF, vídeo, áudio, XLSX, DOCX e CSV.