notesBLOCK
🗒️ Notes: Standalone CLI and MCP server for repo-scoped Markdown notes.
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
Standalone CLI and MCP server for repo-scoped Markdown notes.
notes gives humans and agents one implementation for repository notes, handoff-tagged notes, safe note reads/writes, and an MCP server for agent harnesses.
Full setup, CLI reference, MCP usage, and integration docs are published at .
An optional private capture PWA sends typed or browser-transcribed notes to a configured processing queue.
The Notes Omarchy plugin provides bar access to browse, search, edit, create, and capture notes. Its source lives in omarchy-plugin/, with setup and host integration details in the Omarchy capture documentation.
Agents can use notes-cli for shell commands or notes-mcp for MCP tools. Install them with:
npx skills add timmo001/notes
Stable releases use a manually chosen YYYYMMDD.N version. Create a blank GitHub draft, optionally generate its release notes, then publish it to build Linux archives, deb and RPM packages, and update repo-notes-bin in the AUR. repo-notes-git continues to track relevant changes on main.
Changes under omarchy-plugin/ are validated separately and published from main to timmo001/omarchy-notes. This publication is independent of stable Notes releases.
For local development, run mise run install and mise run build, then use dist/notes.
aaca6f961f77OBSERVED · 2026-10-11Connect
Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control.
claude mcp add notes -- npx -y [email protected]
{
"mcpServers": {
"notes": {
"command": "npx",
"args": [
"-y",
"[email protected]"
]
}
}
}Exposed tools (7)
5 read · 1 write · 1 destructive. Blast radius: 1 tool can delete or overwrite — an agent that can be talked into calling a tool can be talked into calling this one.
| Tool | Risk | Description |
|---|---|---|
Note | read | Description |
Work | read | Continue work |
handoff-name | read | description |
note_delete | destructive | Delete a note file from the notes vault, then commit and best-effort push it. |
note_list | read | List note files in the notes vault for the current project. |
note_read | read | Read the full content and SHA-256 revision of a note file from the notes vault. |
note_write | write | Write a note file to the notes vault, then commit and best-effort push it. |
Trust audit
BLOCKgrade F · trust 53/100 Do not install this without reading the findings. The audit found something that could harm you or your machine.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | WARN |
| L1 | Static analysis of the code | FAIL |
| L2 | Instruction surface (what it tells the agent) | PASS |
| L3 | Class-specific surface | WARN |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- declared (5 observation(s))
- Network
- declared (8 observation(s))
- Shell
- declared (3 observation(s))
- Dependencies
- not all pinned
- Secrets in source
- none-found
Findings (25)
exec(input?: (string | URLPatternInit), baseURL?: string): URLPatternResult | null;
exec(cmd: string[], options?: ContainerExecOptions): Promise<ExecProcess>;
exec(query: string): Promise<D1ExecResult>;
PKGBUILD.bin
ready_cmd = 'curl -fsS "http://127.0.0.1:$PORT/"'
health_cmd = 'curl -fsS "http://127.0.0.1:$PORT/"'
ready_cmd = 'curl -fsS "http://127.0.0.1:$PORT/"'
health_cmd = 'curl -fsS "http://127.0.0.1:$PORT/"'
note_delete
.markdownlint-cli2.jsonc
.yamllint.yml
.dev.vars.example
repo_root=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/../../.." && pwd)cp ../../dist/notes notes
cp ../../LICENSE LICENSE
cp ../../.scripts/linux/PKGBUILD.binary PKGBUILD
cp ../../.scripts/linux/repo-notes.install repo-notes.install
- The daemons are configured in `pitchfork.toml`. Capture serves `http://127.0.0.1:7490/` and docs `http://127.0.0.1:7470/`, or the next free port, and they are always at `https://capture.notes.localh
atob(data: string): string;
declare function atob(data: string): string;
jose, lit, @cloudflare/vite-plugin, @types/bun, prettier, typescript, vite, wrangler
@astrojs/markdown-remark, @astrojs/sitemap, @astrojs/starlight, astro, rehype-external-links, sharp, starlight-contextual-menu, starlight-links-validator
@opentui/core, @tuiparts/core, fuse.js, proper-lockfile, yaml, @types/bun, @types/proper-lockfile, prettier
- Gate: `session.deny(reason)` writes the reason on the main screen, closes the session, and throws `DenyError` to unwind the chain. The server does not report `DenyError` as a failure. If the reason
configured to send it, or from the server session itself, such as a shell rc file. OpenTUI ignores the other keys, such
Gates applied: no_behavioural_pass.
aaca6f961f77full audit observations/trust-audit/mcp-server/timmo001__notes.json · Report an issue / request a re-scanAudit history
Every audit this server has had. A grade with a past is a grade somebody is still checking.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-10-11 | aaca6f961f77 | BLOCK | F | 53 | first audit |
Questions
What is the notes MCP server?
🗒️ Notes: Standalone CLI and MCP server for repo-scoped Markdown notes.
What tools does notes expose?
7 in total: 5 read-only, 1 that write, and 1 that can delete or overwrite (note_delete). Every one is listed on this page with its risk.
Is notes safe to connect to an agent?
No — not without reading the findings first. The audit graded it F (53/100) and found 3 critical or high issues in the source. Each one is listed on this page with the file and line it is on. Separately from the audit: 1 of its tools can destroy data, so scope the token you give it to what you actually need.
What credentials does notes need?
No credential environment variables were found in its source, so it appears to need none.
How current is this page?
The grade is for one exact copy of the source (aaca6f961f77), read on 2026-10-11. The repository is watched and re-audited when it changes.