# Notesnook Local MCP Bridge

An **unofficial, experimental** Notesnook MCP bridge with a Codex desktop plugin for **Linux x64**. Search authorized notes, inspect text and images, and review proposed changes before applying them.

This community project is not affiliated with or endorsed by Notesnook or Streetwriters.

## Before you connect

The bridge runs locally over stdio and uses a separate encrypted profile. It does not open or modify the official desktop app's local database. Account authentication and synchronization use Notesnook's official services through a pinned official core.

**Local execution does not mean notes stay on your computer.** Note content and images returned by tools are sent to your chosen AI service. Read [PRIVACY.md](PRIVACY.md) before authorizing access. Passwords, verification codes and unlock keys are entered locally, never in chat.

Start with an isolated test account. This has not received an independent security audit.

## What it can do

- Search and read ordinary synced notes in locally authorized notebooks, or separately authorized unfiled notes.
- Read block inventories and supported attached images.
- Preview and apply title, tag, notebook membership and supported rich-text changes; create notes through a controlled document schema.
- Preview notebook creation, renaming, hierarchy changes and trash operations when notebook management is enabled locally.
- Check conflicts and single-use plans, inspect operation status, and prepare recovery previews.
- Diagnose installation and runtime state, and back up or restore the encrypted profile into a new directory.

There are 19 MCP tools. Locked, local-only, deleted and unauthorized notes remain inaccessible. Selecting a parent notebook does not authorize its children. Recovery has conditions; it is not a substitute for an independent backup.

## Install

Use the Linux x64 release archive and its matching `.sha256` file once published. Keep the entire extracted delivery at a permanent location, then run:

```sh
sh ./install.sh --check
sh ./install.sh --install
sh ./install.sh --verify
```

Run each command only after the previous one succeeds. The installer prints the installed `setup-local.sh` path. Open it locally to sign in, synchronize and save the access scope. In a new chat select **Notesnook Local MCP Bridge** and check `notes_status` before using notes.

The installation workflow targets a Codex desktop host with compatible local-plugin CLI support. Other MCP clients, browser-only sessions, phones, Windows and macOS have not been validated. Requires Python3, libsecret, flock and a signed-in Linux desktop session with an available unlocked Secret Service. Node and program dependencies are bundled in the binary delivery.

See [installation](docs/linux-delivery.md), [diagnostics](docs/diagnosis.md), [profile backup](docs/profile-backup.md) and [known limitations](docs/limitations.md).

## Build and inspect

```sh
sh scripts/setup.sh --check
sh scripts/setup.sh --prepare
npm run verify
npm run release
# Use the exact RELEASE.json path printed by the release command:
npm run export -- /absolute/path/to/RELEASE.json
```

Preparation downloads dependencies and compiles native modules. Read [development](docs/development.md) first. It does not sign into an account. Runtime uses pinned Node 22.20.0 and Notesnook core 8.1.3 at commit `623ceb4b23e23db44bd1e8ab16fbe4a46f1ccfa7`, plus the documented sodium interoperability patch.

Builds record a source digest, package digest and build ID. These identify content and detect changes; they do not certify safety, author identity or security. See [architecture](docs/architecture.md) and [validation](VALIDATION.md).

## Source and license

GPL-3.0-or-later; see [LICENSE](LICENSE) and [third-party notices](THIRD_PARTY_NOTICES.md). The public source snapshot excludes local profiles, private service deployment scripts, personal note materials, local reports and the author's previous Git history. Synthetic multilingual tests remain intentional.

The protocol adapter modules named `private-*` are retained for isolated compatibility regression tests. They are not a hosted service, do not include credentials, and are not configured or started by the local plugin installer.

Please read [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md) before sharing reports. Do not attach account databases, credentials, private notes, local setup URLs or raw logs.