Bear Notes MCP Server

An unofficial, opinionated MCP for Bear Notes — built around relevance-ranked search across titles, bodies, and hierarchical tags. Reads run direct against Bear's SQLite database. Offline-first, network-free.

Full documentation and source code: bear-notes-mcp

Key Features

• Read-only by default — flip Edit Mode for writes. 4 tools always on for search and reading; 8 more in Edit Mode for creation, editing, and tag management
• Relevance-ranked search across titles, bodies, and hierarchical tags — finds the right note, not just literal-match ones
• Library-wide tag operations — rename or delete a tag everywhere, atomically
• Sectioned writes — append at a specific heading or replace a section
• File attachments — attach images, PDFs, and documents up to 25 MB; symlinks rejected for safety
• Date-based search with relative dates ("yesterday", "last week", etc.)
• Configurable new note convention for tag placement (opt-in)
• Local-first — direct read-only SQLite, no network, no telemetry, no Bear app needed to query
• Supply-chain clean — native node:sqlite, no unsigned third-party binaries

Tools

• bear-open-note - Read the full text content of a Bear note by its ID or title, including OCR'd text from attached images and PDFs
• bear-create-note - Create a new note in your Bear library with optional title, content, and tags
• bear-search-notes - Find notes by relevance across titles, body, and OCR-extracted text from attached images and PDFs. Use a phrase or a few keywords describing what you're looking for; results are ranked by relevance and each includes a context snippet. Also supports tag, date-range, and pinned-only filters — combine with a search term or use them on their own to browse.
• bear-add-text - Insert text at the beginning or end of a Bear note, or within a specific section identified by its header. Requires the note's current revision token (the Revision: N line from your last response that referenced it); writes against a stale revision are rejected with an instruction to re-read with bear-open-note before retrying.
• bear-replace-text - Replace content in an existing Bear note — either the full body or a specific section. Requires the note's current revision token (the Revision: N line from your last response that referenced it); writes against a stale revision are rejected with an instruction to re-read with bear-open-note before retrying.
• bear-add-file - Attach a local file (image, PDF, document) to an existing Bear note by its ID or title. Bear extracts text from images and PDFs via OCR, making attachment content searchable. Requires the note's current revision token (the Revision: N line from your last response that referenced it); writes against a stale revision are rejected with an instruction to re-read with bear-open-note before retrying.
• bear-list-tags - List all tags in your Bear library as a hierarchical tree with note counts
• bear-find-untagged-notes - Find notes in your Bear library that have no tags assigned
• bear-add-tag - Add one or more tags to an existing Bear note. Requires the note's current revision token (the Revision: N line from your last response that referenced it); writes against a stale revision are rejected with an instruction to re-read with bear-open-note before retrying.
• bear-archive-note - Archive a Bear note to remove it from active lists without deleting it
• bear-rename-tag - Rename a tag across all notes in your Bear library
• bear-delete-tag - Delete a tag from all notes in your Bear library without affecting the notes
• bear-capabilities - Report the current server mode (read-only or Edit Mode) and how to unlock additional capabilities

Requirements: Node.js 24.13.0+

Quick Start - Claude Code (One Command)

claude mcp add -s user bear-notes -- npx -y bear-notes-mcp@latest

That's it! The server will be downloaded from npm and configured automatically.

Quick Start - Other AI Assistants

Add to your MCP configuration file:

{
  "mcpServers": {
    "bear-notes": {
      "command": "npx",
      "args": ["-y", "bear-notes-mcp@latest"]
    }
  }
}

Configuration

Variable	Default	Description
UI_DEBUG_TOGGLE	false	Enable debug logging for troubleshooting
UI_ENABLE_NEW_NOTE_CONVENTION	false	Place tags right after the note title instead of at the bottom
UI_ENABLE_CONTENT_REPLACEMENT	false	Edit Mode — enables all 8 write tools (create, add, replace, attach, tag mgmt, archive). Off by default; the server is read-only without it.

Example with configuration:

{
  "mcpServers": {
    "bear-notes": {
      "command": "npx",
      "args": ["-y", "bear-notes-mcp@latest"],
      "env": {
        "UI_ENABLE_NEW_NOTE_CONVENTION": "true",
        "UI_ENABLE_CONTENT_REPLACEMENT": "true",
        "UI_DEBUG_TOGGLE": "true"
      }
    }
  }
}

Advanced: Local Development Build

Step 1: Clone and build

git clone https://github.com/vasylenko/bear-notes-mcp.git
cd bear-notes-mcp
npm install
npm run build

Step 2: Configure with local path

For Claude Code:

claude mcp add -s user bear-notes -- node /absolute/path/to/dist/main.js

For other AI assistants:

{
  "mcpServers": {
    "bear-notes": {
      "command": "node",
      "args": ["/absolute/path/to/dist/main.js"]
    }
  }
}