ocean-brain CLI

The npm distribution for Ocean Brain. It provides two commands:

• ocean-brain serve runs the packaged Ocean Brain web app and server.
• ocean-brain mcp connects an MCP client to a running Ocean Brain instance over stdio.

For the product overview and screenshots, see the Ocean Brain project.

Requirements

Use Node.js 22.13+ or a newer LTS release. A global installation is not required; the examples below use npx.

serve

serve is the default command, so npx ocean-brain and npx ocean-brain serve are equivalent.

For a password-protected workspace, set both the shared workspace password and a separate session secret:

OCEAN_BRAIN_PASSWORD='choose-a-strong-password' \
OCEAN_BRAIN_SESSION_SECRET='paste-a-long-random-secret-here' \
npx -y ocean-brain serve --host 127.0.0.1

Open http://localhost:6683. Generate the session secret once—for example with openssl rand -hex 32—keep it private, and reuse it across restarts. Startup fails unless password mode or open mode is selected explicitly; do not enable both.

One running instance is one shared workspace. Password mode protects the entire instance with one shared password; it does not provide individual accounts, roles, or per-note permissions. If you bind beyond localhost, keep password mode enabled and place Ocean Brain behind HTTPS.

Local-only open mode

Open mode has no login. Use it only on your own machine and keep the loopback binding:

npx -y ocean-brain serve \
  --host 127.0.0.1 \
  --allow-insecure-no-auth

Options and environment

| Setting | Behavior | |---|---| | -H, --host <host> | Bind address; defaults to 0.0.0.0 | | -p, --port <port> | Listen port; defaults to 6683 | | --allow-insecure-no-auth | Explicitly enable open mode | | HOST, PORT | Override their corresponding CLI options | | OCEAN_BRAIN_PASSWORD | Shared password for password mode | | OCEAN_BRAIN_SESSION_SECRET | Session secret required in password mode | | OCEAN_BRAIN_ALLOW_INSECURE_NO_AUTH=true | Environment equivalent of the open-mode flag | | OCEAN_BRAIN_DATA_DIR | Data directory; defaults to ~/.ocean-brain/data | | OCEAN_BRAIN_IMAGE_DIR | Uploaded-image directory; defaults to ~/.ocean-brain/assets/images | | DATABASE_URL | SQLite file URL; takes precedence over the database path derived from the data directory |

By default, notes are stored in ~/.ocean-brain/data/db.sqlite3 and uploaded images in ~/.ocean-brain/assets/images. The CLI creates the directories and applies bundled database migrations at startup. Stop Ocean Brain and back up both paths together; restore them while the server remains stopped.

Configure the embedding API URL and optional API key under Settings > Search. The saved key stays on the server and is not returned to the browser.

Deleted notes remain in Trash for 30 days. Note snapshots are retained for up to 7 days, with at most 10 snapshots per note. These recovery tools and individual exports do not replace a full backup.

For a long-lived installation, replace ocean-brain in the commands with an exact version such as [email protected].

mcp

The mcp command starts the built-in stdio MCP adapter that forwards tool calls to an existing Ocean Brain instance. It does not start the web app.

The MCP tools can search and read notes, query tags and properties, create notes, make targeted Markdown or metadata edits, and move notes to Trash.

First enable MCP access under Settings > MCP, issue a token, and save it to a local file. Then configure the MCP client, for example:

{
  "mcpServers": {
    "ocean-brain": {
      "command": "npx",
      "args": [
        "-y",
        "ocean-brain",
        "mcp",
        "--server",
        "http://localhost:6683",
        "--token-file",
        "/absolute/path/to/ocean-brain/mcp-token"
      ]
    }
  }
}

Set --server to the Ocean Brain URL reachable from the machine running the MCP client. Replace localhost when the instance is remote or behind a proxy.

Options

| Option | Behavior | |---|---| | -s, --server <url> | Ocean Brain server URL; defaults to http://localhost:6683 | | --token-file <path> | Read the bearer token from a file; takes precedence over --token | | --token <token> | Direct bearer-token fallback |

The built-in adapter expands token-file paths that begin with ~, $HOME, ${HOME}, %USERPROFILE%, or %HOME%. This keeps copied JSON configurations portable even when the MCP client does not run arguments through a shell. Settings > MCP can generate either macOS/Linux shell commands or Windows PowerShell commands.

Prefer --token-file so the token is not stored directly in client configuration. Ocean Brain keeps one active MCP token; rotating or revoking it immediately invalidates the previous token. For a long-lived MCP setup, pin an npm package version compatible with the requirement shown in Settings > MCP.

Links

• Product documentation
• Releases
• Source code
• Issues
• MIT License