# io.github.KuvopLLC/better-bear (npm · better-bear)

MCP server for Bear notes — read, search, create, edit, tag, and manage notes via CloudKit

- Trust score: 66/100 (medium)
- Change this week: +20
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-03

## Components

- npm · `better-bear`: 66/100 (this document), [markdown](https://verifymcp.io/servers/kuvopllc-better-bear/better-bear.md), [page](https://verifymcp.io/servers/kuvopllc-better-bear/better-bear)

## Channel facts

- Registry: `npm`
- Package: `better-bear`
- Version: `0.4.26`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-03.

- **Supply Chain Security**: 86/100
  - No malware found by supply-chain analysis.
  - Only part of the dependency tree could be resolved (94 of 98), so this covers what we could see, not the whole tree.
  - No install/post-install scripts declared.
  - Only part of the dependency tree could be resolved (94 of 98), so this covers what we could see, not the whole tree.
- **Provenance & Transparency**: 45/100
  - Source repository is publicly reachable at the declared URL.
  - Provenance check failed: no build-provenance attestation is published.
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 101 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 81/100
  - AI-judged instruction clarity (excellent).
  - Tool/resource definitions use about 3297 tokens (~94/item across 35 items; 35 tools + 0 resources), lean.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 0/100
  - Stability not yet verified: not enough scan history yet (needs a 30-day window).
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

**Unverified: 1 category.** A category scored 0 because we could not verify it: a data source with nothing on this package, evidence we could not reach, or a check we could not run. We only credit what we can confirm.

## Install

### Claude

```bash
claude mcp add kuvopllc-better-bear -- npx -y better-bear
```

### Codex

```bash
codex mcp add kuvopllc-better-bear -- npx -y better-bear
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "kuvopllc-better-bear": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "better-bear"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add kuvopllc-better-bear --command npx --arg -y --arg better-bear
```

### Hermes

```yaml
mcp_servers:
  kuvopllc-better-bear:
    command: "npx"
    args: ["-y", "better-bear"]
```

### Other

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

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-02 (score 66, +45)

- [security regression] Provenance: unverified → fail
- [security improvement] Install scripts: unverified → pass
- [security improvement] Known CVEs: unverified → partial
- [security improvement] Malware scan: unverified → pass
- [security] Stability: Stability not yet verified: not enough scan history yet (needs a 30-day window).
- [functional regression] Security disclosure: fail → unverified
- [functional improvement] Schema quality: unverified → excellent
- [functional improvement] License: unverified → pass
- [functional improvement] Dependency health: unverified → partial
- [functional improvement] Maintenance: unverified → pass
- [functional improvement] MCP protocol: unverified → pass
- [functional] Licence: MIT

### 2026-08-01 (score 21, +16)

- [functional improvement] Tool coverage: unverified → 100

### 2026-07-31 (score 5, −41)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-27 (score 46)

First indexed and scored.

## MCP tools (35)

### `bear_list_notes` (~206 tokens)

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.

Input parameters:

- `include_archived` (boolean): Include archived notes in results
- `include_trashed` (boolean): Include trashed notes in results
- `limit` (number): Maximum number of notes to return (default 30)
- `tag` (string): Filter notes by tag (partial match)

### `bear_get_note` (~132 tokens)

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.

Input parameters:

- `id` (string, required): Note ID (uniqueIdentifier)
- `raw` (boolean): Return only the raw markdown content

### `bear_search` (~165 tokens)

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.

Input parameters:

- `before` (string): Only notes modified before this date (YYYY-MM-DD)
- `limit` (number): Maximum number of results (default 20)
- `query` (string, required): Search query text
- `since` (string): Only notes modified after this date (YYYY-MM-DD, or: today, yesterday, last-week, last-month)

### `bear_get_tags` (~36 tokens)

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` (~199 tokens)

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.

Input parameters:

- `body` (string): Note body text (markdown)
- `frontmatter` (object): YAML front matter fields as key-value pairs (e.g. {status: 'draft', project: 'alpha'})
- `tags` (array): Tags to assign to the note
- `title` (string, required): Note title

### `bear_edit_note` (~207 tokens)

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.

Input parameters:

- `after` (string): Insert appended text after the line containing this text (use with append_text)
- `append_text` (string): Text to append to the end of the note
- `body` (string): New content to replace the entire note body
- `id` (string, required): Note ID (uniqueIdentifier)
- `remove_frontmatter` (array): Front matter field keys to remove
- `replace_section` (string): Replace content under this heading (replaces until next heading of same or higher level)
- `section_content` (string): New content for the section (use with replace_section)
- `set_frontmatter` (object): Front matter fields to set or update (key-value pairs)

### `bear_trash_note` (~54 tokens)

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.

Input parameters:

- `id` (string, required): Note ID (uniqueIdentifier)

### `bear_sync` (~70 tokens)

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.

Input parameters:

- `full` (boolean): Force a full re-sync instead of incremental

### `bear_list_todos` (~60 tokens)

List Bear notes that have incomplete TODO items (markdown checkboxes like '- [ ]'). Returns each note's title, tags, and counts of complete/incomplete items.

Input parameters:

- `limit` (number): Maximum number of notes to return (default 30)

### `bear_get_todos` (~56 tokens)

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

Input parameters:

- `id` (string, required): Note ID (uniqueIdentifier)

### `bear_toggle_todo` (~76 tokens)

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.

Input parameters:

- `id` (string, required): Note ID (uniqueIdentifier)
- `item_index` (number, required): 1-based index of the TODO item to toggle

### `bear_attach_file` (~175 tokens)

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.

Input parameters:

- `after` (string): Insert after the line containing this text
- `before` (string): Insert before the line containing this text
- `file_path` (string, required): Absolute path to the file to attach
- `id` (string, required): Note ID (uniqueIdentifier)
- `prepend` (boolean): Insert after the title line instead of at the end

### `bear_archive_note` (~61 tokens)

Archive a Bear note. Archived notes are hidden from the main list but not deleted. Use 'undo' to unarchive.

Input parameters:

- `id` (string, required): Note ID (uniqueIdentifier)
- `undo` (boolean): Unarchive the note instead of archiving

### `bear_add_tag` (~87 tokens)

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.

Input parameters:

- `id` (string, required): Note ID (uniqueIdentifier)
- `tag` (string, required): Tag to add (without #)

### `bear_remove_tag` (~90 tokens)

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.

Input parameters:

- `id` (string, required): Note ID (uniqueIdentifier)
- `tag` (string, required): Tag to remove (without #)

### `bear_rename_tag` (~56 tokens)

Rename a tag across all Bear notes. Every note containing the old tag will be updated.

Input parameters:

- `new_name` (string, required): New tag name (without #)
- `old_name` (string, required): Current tag name (without #)

### `bear_delete_tag` (~40 tokens)

Delete a tag from all Bear notes. The tag text is removed but notes are preserved.

Input parameters:

- `tag` (string, required): Tag to delete (without #)

### `bear_find_untagged` (~38 tokens)

List Bear notes that have no tags assigned.

Input parameters:

- `limit` (number): Maximum number of notes to return (default 30)

### `bear_note_stats` (~50 tokens)

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` (~40 tokens)

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` (~58 tokens)

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` (~137 tokens)

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.

Input parameters:

- `dir` (string): Output directory for the context library (default: ~/.bear-context)
- `tag_prefix` (string): Tag prefix for qualifying notes (default: context). Notes tagged #context or #context/subtag will be included.
- `use_frontmatter` (boolean): Also include notes with context: true in YAML front matter (default: true)

### `bear_context_sync` (~96 tokens)

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.

Input parameters:

- `force` (boolean): Force full re-sync (re-download all notes)

### `bear_context_index` (~60 tokens)

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` (~78 tokens)

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.

Input parameters:

- `paths` (array, required): File paths relative to context directory (e.g., 'bear/my-note.md')

### `bear_context_search` (~77 tokens)

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.

Input parameters:

- `limit` (number): Maximum results (default: 5)
- `query` (string, required): Search query (case-insensitive substring match)

### `bear_context_add` (~88 tokens)

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.

Input parameters:

- `id` (string, required): Note ID (uniqueIdentifier)
- `subtag` (string): Optional sub-tag for grouping (e.g., 'architecture', 'jira')

### `bear_context_remove` (~46 tokens)

Remove a Bear note from the context library by removing its #context tag. Triggers a sync to delete the local file.

Input parameters:

- `id` (string, required): Note ID (uniqueIdentifier)

### `bear_context_status` (~57 tokens)

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` (~159 tokens)

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.

Input parameters:

- `content` (string, required): Markdown content to import
- `filename` (string, required): Target filename in external/ (e.g., 'jira-ticket-123.md')
- `group` (string): Group label for organizing (e.g., 'jira', 'slack', 'docs')
- `source` (string): Source description (e.g., URL, tool name)
- `summary` (string): Short summary of the content

### `bear_context_ingest` (~61 tokens)

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` (~185 tokens)

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.

Input parameters:

- `action` (string, required): Triage action: keep (move to external/), push_to_bear (create Bear note), or discard (delete)
- `filename` (string, required): Filename in inbox/ to triage
- `group` (string): Group label (used with 'keep' action)
- `subtag` (string): Sub-tag for Bear note (used with 'push_to_bear' action, e.g., 'jira' → #context/jira)
- `summary` (string): Short summary (used with 'keep' action)

### `bear_context_push_to_bear` (~115 tokens)

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.

Input parameters:

- `filename` (string, required): Filename in external/ to push
- `subtag` (string): Sub-tag (e.g., 'architecture' → #context/architecture)
- `title` (string): Override note title (defaults to title extracted from content)

### `bear_context_set_prefix` (~128 tokens)

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.

Input parameters:

- `new_prefix` (string, required): New tag prefix without the leading #. Example: '10-projects'.

### `bear_context_remove_external` (~54 tokens)

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.

Input parameters:

- `filename` (string, required): Filename in external/ to remove

## Diagnostics

Captured diagnostic sections: Provenance, Dependencies. The full working is on the page: https://verifymcp.io/servers/kuvopllc-better-bear/better-bear#diagnostics

## Score history

- 2026-08-03: 66
- 2026-08-02: 66
- 2026-08-01: 21
- 2026-07-31: 5
- 2026-07-30: 46
- 2026-07-28: 46
- 2026-07-27: 46

## Links

- npm package: https://www.npmjs.com/package/better-bear
- Socket report: https://socket.dev/npm/package/better-bear
- Repository: https://github.com/KuvopLLC/better-bear
- Changelog RSS feed: https://verifymcp.io/servers/kuvopllc-better-bear/better-bear/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/kuvopllc-better-bear/better-bear/changelog.json
- HTML version of this page: https://verifymcp.io/servers/kuvopllc-better-bear/better-bear