Better Bear

What KuvopLLC/better-bear MCP server does

KuvopLLC/better-bear MCP server connects an MCP client to a Bear notes library through CloudKit. It supports reading and changing notes, while also exposing operations for tags, TODO checkboxes, attachments, archives, statistics, duplicate detection, and library health checks.

Note retrieval includes titles, markdown content, tags, modification dates, and lock status. Search covers titles, tags, and body text, with relevance ordering and snippets for body matches. Bear's hierarchical tags are represented in two ways: the CloudKit index can include ancestor tags, while attached tags show only the leaf tags on each branch.

The server also includes a context library for preparing selected Bear notes for LLM use. Notes tagged with a configurable context prefix can be synchronized into a local bear/ directory. The library also supports external/ content and an inbox/ directory, with an index that helps clients locate relevant files before fetching their full contents.

How it works

The MCP tools communicate with Bear data through iCloud CloudKit. bear_sync can request an incremental update or a complete resynchronization, although normal read operations generally refresh stale cached data automatically. Creating or editing a note changes its Bear content, while tagging operations update the note markdown and tag index as appropriate.

For TODO work, first retrieve the items with bear_get_todos; the returned one-based index is then passed to bear_toggle_todo. Attachments are uploaded to iCloud and embedded in the note's markdown. Moving a note to the trash is a soft delete, and archiving hides a note without deleting it.

The context workflow is index-first. Initialize it once with bear_context_setup, synchronize qualifying notes with bear_context_sync, inspect the generated index using bear_context_index, and fetch only the files needed for a task. bear_context_search can search Bear-derived files, external files, and inbox content without loading the entire library.

Setup and configuration

The repository documents installation through the bcli command-line tool. The install script places the CLI, after which bcli auth authenticates with iCloud and bcli mcp install configures the MCP server. The setup supports Claude Desktop and Claude Code; desktop-only, code-only, JSON configuration, and release-bundle options are also documented.

The server can also be launched directly for an MCP client with npx -y better-bear. Authentication is still required for access to the Bear library. The context library is initialized separately and can then be managed through MCP tools or the corresponding CLI commands.

Tools and capabilities

• List, fetch, create, edit, trash, archive, and search Bear notes.
• Add, remove, rename, and delete tags, including hierarchical tags.
• List incomplete TODO notes, inspect TODO items, and toggle completion.
• Attach images or other supported files to notes at selected positions.
• Inspect tag hierarchies, library statistics, duplicates, untagged notes, and health warnings.
• Synchronize Bear data incrementally or with a full refresh.
• Initialize, sync, search, inspect, fetch, and maintain the context library.
• Import external text into the context library with YAML front matter.

Limitations and notes

Locked or private Bear notes can be returned with metadata, but their body content is not searchable. A title-only search result or a missing body match may indicate that the note is locked. Use bear_get_note to inspect a specific note when appropriate.

Front matter changes cannot be combined with body replacement or text appending in the same edit operation. TODO indexes are one-based and should be obtained from the note's TODO listing before toggling an item.

The context synchronization process only manages the bear/ directory. It does not overwrite external/ or inbox/. Removing a context tag, trashing a note, or otherwise making it ineligible causes the corresponding synchronized file to be removed during a context sync. KuvopLLC/better-bear MCP server is licensed under MIT according to the repository badge.