← Back to directory
B

Bear Notes MCP Server

Community
An unofficial, local-first MCP server for Bear Notes with relevance-ranked search and edit mode.
GitHub source repository ↗
★ 206 Stars Category · Other Popular Source revision be87b37ab4bf
44FMRS · D
Reliability
8/20
Security and permissions
10/20
Maintenance
8/20
Documentation
9/20
Setup experience
9/20

This server offers powerful search and editing capabilities for Bear Notes, but it's unofficial and requires user awareness of permissions and risks. It's well-suited for privacy-conscious local-first users, but not for those unfamiliar with MCP or with simple small-library needs.

Read the FMRS scoring method →

Bear Notes MCP Server is an unofficial, opinionated MCP server for Bear Notes. It provides relevance-ranked search instead of substring matching, with results ranked across titles, bodies, and hierarchical tags, complete with snippets and combinable filters (tag, date, pinned). Reads run directly against Bear's SQLite database, no Bear app required for queries. Writes route through Bear's own URL handler, atomic and validated by Bear. Offline-first: no network calls, no telemetry. Works with any MCP client. Ships as a one-click .mcpb extension for Claude Desktop or a standalone npm package.

Tools

bear-capabilities
Report the current server mode (read-only or Edit Mode) and how to unlock additional capabilities.
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. Supports tag, date-range, and pinned-only filters.
bear-add-text
Insert text at the beginning or end of a note, or within a specific section. Requires the note's current revision token.
bear-replace-text
Replace content in an existing note, either the full body or a specific section. Requires the note's current revision token.
bear-add-file
Attach a local file (image, PDF, document) to an existing note. Max 25 MB; symlinks rejected.
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 note. Requires the note's current revision token.
bear-archive-note
Archive a 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.

Setup

Claude Desktop Extension:

  1. Download the latest bear-notes-mcpb-*.mcpb file from [Releases](https://github.com/vasylenko/bear-notes-mcp/releases).
  2. Ensure Claude Desktop is running.
  3. Double-click the extension file and follow the installation prompt.

Standalone MCP Server (other clients):
- Requires Node.js 24.13.0+.
- For Claude Code: claude mcp add -s user bear-notes -- npx -y bear-notes-mcp@latest.
- For other clients, add the JSON configuration to your MCP configuration file.

Example config:

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

Fit and risk

Best for

  • Users with large note libraries where substring search is insufficient.
  • Users switching between multiple MCP clients (Claude Desktop, Claude Code, Cursor, Codex, Gemini, etc.).
  • Users who want to query notes without opening Bear.
  • Users needing library-wide tag management.
  • Users concerned about supply-chain hygiene and privacy.

Not for

  • Users with small libraries who just want quick note integration.
  • Users unwilling to grant MCP server access to local database.
  • Users needing Windows or Linux support (macOS only).
  • Users requiring official support or guarantees (unofficial project).

Required permissions

  • Read access to Bear Notes SQLite database.
  • Write access via Bear's X-callback-URL API when Edit Mode is enabled.
  • Optional attachment of local files (max 25 MB).
  • Optional communication with AI provider when using an AI assistant (data sent to your provider).

Risks and side effects

  • Extension installation shows a red warning about granting access to everything on your computer, but actually only accesses Bear's database.
  • Write operations require Edit Mode and may overwrite data if revision tokens are stale.
  • Unofficial project; there may be bugs, but the codebase is small and reviewable.
  • macOS only.

Troubleshooting

  1. Ensure Node.js version meets requirements (24.13.0+).
  2. Ensure Bear app is installed (required for write operations).
  3. For Claude Desktop, check logs: `~/Library/Logs/Claude/main.log` and `~/Library/Logs/Claude/mcp-server-Bear Notes.log`.
  4. Set environment variable `UI_DEBUG_TOGGLE=true` for verbose logging.
  5. If double-clicking the .mcpb file doesn't work, install manually via Claude Settings → Extensions.

Use cases

Searching years of accumulated notes with relevance-ranked results.
Querying your notes mid-conversation without bringing Bear to the foreground.
Managing tags across the whole library, including renaming and deleting.
Pulling notes into AI conversations for outlines, summaries, or drafting.
Automating note creation and editing via Edit Mode.

Supported clients

Claude DesktopFull support
Claude CodeFull support
CursorFull support
CodexFull support
GeminiFull support
WindsurfFull support