# KuvopLLC/better-bear [Health: Active]

**Category:** 🏢 Workplace & Productivity  
**Repository:** https://github.com/KuvopLLC/better-bear/tree/main/mcp-server  
**GitHub Stars:** 64  
**npm Downloads (last month):** 669  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/kuvopllc-better-bear

## Description
MCP server for Bear notes via CloudKit — CRUD, tags, TODOs, attachments, search, front matter, stats, and health checks. Install via npx better-bear.

## Tools
Capabilities this server exposes over MCP:

- **bear_list_notes** — List Bear notes with optional tag filtering. Returns an array of notes with IDs, titles, tags, pin status, and modification dates. Each note includes two tag fields: 'tags' mirrors Bear's CloudKit index verbatim (includes ancestor expansions — a note tagged #parent/child will show both 'parent' and 'parent/child'); 'attached_tags' shows only leaf tags (the most-specific tag on each branch). Notes with 'locked: true' are private/encrypted in Bear and their body content is not searchable — if a search returns no results, check whether the relevant note is locked. Use bear_get_note to read the full content of a specific note.
- **bear_get_note** — Get a single Bear note's full content and metadata by ID. Returns the note title, tags, full markdown text, and dates. The response includes 'tags' (CloudKit index, may contain ancestor tags like 'parent' for a note tagged '#parent/child') and 'attached_tags' (leaves only). If the note is locked/private, 'locked: true' will be included in the response. Use the 'raw' option to get just the markdown without metadata.
- **bear_search** — Full-text search across Bear note titles, tags, and body content. Returns matching notes ranked by relevance (title matches first, then tag, then body). Body matches include a text snippet with surrounding context. Locked/private notes will match by title but may not match body searches — results include 'locked: true' for these notes. If you can't find content you expect, try listing notes to check if the relevant note is locked.
- **bear_get_tags** — Get the full tag hierarchy from Bear. Returns all tags with their note counts and pin status. Useful for understanding how notes are organized.
- **bear_create_note** — Create a new Bear note with a title, optional body text, tags, and YAML front matter. Hashtags written inline in the body (e.g. '#my_tag' or '#parent/child') are extracted and registered as real tags on the note, matching Bear's desktop-app behaviour. Tags from the 'tags' array are indexed regardless of whether they appear in the body. Hierarchical tags like '#parent/child' also index every ancestor (so they show up under #parent in Bear's sidebar). Front matter is stored as a collapsed metadata block at the top of the note. Returns the new note's ID.
- **bear_edit_note** — Edit an existing Bear note. Provide 'append_text' to add text, 'body' to replace content, or 'set_frontmatter'/'remove_frontmatter' to edit YAML front matter fields. Front matter edits can be combined with each other but not with body/append.
- **bear_trash_note** — Move a Bear note to the trash. This is a soft delete — the note can be recovered from Bear's trash. The note is identified by its ID.
- **bear_sync** — Trigger a sync of Bear notes from iCloud. Normally an incremental sync fetching only changes. Use 'full' to force a complete re-sync. Most read operations auto-sync when the cache is stale, so manual sync is rarely needed.
- **bear_list_todos** — List Bear notes that have incomplete TODO items (markdown checkboxes like '- [ ]'). Returns each note's title, tags, and counts of complete/incomplete items.
- **bear_get_todos** — Get all TODO items from a specific Bear note. Returns each item's text, completion status, and index number (use the index with bear_toggle_todo to toggle items).
- **bear_toggle_todo** — Toggle a specific TODO item in a Bear note between complete and incomplete. The item_index is 1-based — use bear_get_todos first to see the list with index numbers.
- **bear_attach_file** — Attach a file or image to an existing Bear note. The file is uploaded to iCloud and embedded in the note's markdown. Supports common image formats (jpg, png, gif, webp, heic) and other file types (pdf, zip, etc.). By default the attachment is appended to the end. Use 'after' or 'before' to place it relative to text in the note, or 'prepend' to put it right after the title.
- **bear_archive_note** — Archive a Bear note. Archived notes are hidden from the main list but not deleted. Use 'undo' to unarchive.
- **bear_add_tag** — Add a tag to an existing Bear note. The tag is inserted into the note's markdown. Hierarchical tags like 'parent/child' also index every ancestor — so the note becomes discoverable under both #parent and #parent/child in Bear's sidebar.
- **bear_remove_tag** — Remove a tag from a specific Bear note. Works on any tag visible in 'tags' on the note — including ancestor tags like 'parent' that exist only as hierarchical expansions. Removing a hierarchical leaf like 'parent/child' also drops orphaned ancestors from the tag index.
- **bear_rename_tag** — Rename a tag across all Bear notes. Every note containing the old tag will be updated.
- **bear_delete_tag** — Delete a tag from all Bear notes. The tag text is removed but notes are preserved.
- **bear_find_untagged** — List Bear notes that have no tags assigned.
- **bear_note_stats** — Get statistics about the Bear notes library: total notes, words, tags, pinned, archived, trashed, notes with TODOs, oldest/newest dates, and top 10 tags by note count.
- **bear_find_duplicates** — Find notes with duplicate titles. Returns groups of notes sharing the same title with their IDs and modification dates. Useful for cleaning up after imports or sync conflicts.
- **bear_health_check** — Run a health check on the Bear notes library. Reports duplicate titles, empty notes, notes stuck in trash, sync conflicts, orphaned tags, untagged notes, and oversized notes. Use this to identify cleanup opportunities or diagnose sync issues.
- **bear_context_setup** — Initialize a context library — a curated, synced folder of Bear notes optimized for LLM consumption. Creates the directory structure and config. After setup, tag Bear notes with #context (or a custom prefix) and use bear_context_sync to pull them in. One-time operation.
- **bear_context_sync** — Sync qualifying Bear notes to the local context library. Adds new notes, updates changed notes, and removes notes that no longer qualify (tag removed, trashed, etc.). Regenerates the index. Only touches the bear/ directory — external/ and inbox/ are untouched. Call this when the user asks to sync, refresh, or update their context.
- **bear_context_index** — Get the context library index — a structured table of contents of all files (Bear notes, external files, inbox). Read this FIRST before answering questions from context. Use it to identify which files to fetch, rather than loading everything. Includes cache freshness metadata.
- **bear_context_fetch** — Load the full content of specific files from the context library. Pass relative paths like 'bear/arch-overview.md' or 'external/jira-ticket.md'. Use after reading the index to load only relevant files — never load everything.
- **bear_context_search** — Full-text search across the entire context library (Bear notes + external files + inbox). Returns matching snippets with filenames and origin labels. Use when the index alone isn't enough to find the right file.
- **bear_context_add** — Add a Bear note to the context library by tagging it with #context. Optionally specify a subtag for grouping (e.g., subtag 'jira' → #context/jira). Triggers a sync after tagging.
- **bear_context_remove** — Remove a Bear note from the context library by removing its #context tag. Triggers a sync to delete the local file.
- **bear_context_status** — Get context library health and stats: Bear note count, external file count, inbox count, total tokens, last sync time, group breakdown, and warnings (stale cache, expired externals, oversized files, untriaged inbox items).
- **bear_context_import** — Import external content into the context library. Content is written to the external/ directory with YAML front matter (source, group, summary, date). Use this to add non-Bear content like Jira tickets, Slack threads, API docs, or any markdown. The content is passed via stdin and a filename must be provided.
- **bear_context_ingest** — Scan the inbox/ directory and list all untriaged files. Returns filename, size, content preview (first 500 chars), and any detected YAML front matter for each file. Does NOT modify anything — use bear_context_triage to act on files.
- **bear_context_triage** — Triage a file in the inbox. Three actions: 'keep' moves it to external/ with optional group/summary metadata. 'push_to_bear' creates a Bear note tagged #context (+ optional subtag) and deletes the inbox file. 'discard' deletes the file. All actions regenerate the index.
- **bear_context_push_to_bear** — Push an external file to Bear as a new note. Creates a Bear note from the file content, tags it with #context (+ optional subtag), and removes the original external file. Use when external content has matured enough to become a permanent Bear note.
- **bear_context_set_prefix** — Change the context library's tag prefix and re-tag every Bear note that currently uses the old prefix. Sub-tags are preserved — `#context/research` becomes `#<new>/research`. Updates both the markdown body and the CloudKit tag index, and persists the new prefix to the context config. Useful when aligning the qualifier tag with a broader naming scheme like Johnny Decimal (e.g. '10-projects'). Run `bear_context_sync` afterwards to refresh the library.
- **bear_context_remove_external** — Remove a file from the external/ directory in the context library. Deletes the file and regenerates the index. Use when external content is no longer needed.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "better-bear": {
    "command": "npx",
    "args": ["-y","better-bear"]
  }
}
```

## Documentation

## 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.

_Full upstream README: https://allmcps.com/mcp/kuvopllc-better-bear/readme_