better-bear-mcp

MCP server that gives Claude access to your Bear notes.

Powered by better-bear-cli (bcli), it exposes Bear's note operations as MCP tools over stdio transport.

Prerequisites

• macOS (Bear is macOS-only)
• Bear installed with iCloud sync enabled
• Node.js 20+
• An iCloud account (for CloudKit authentication)

Installation

For Claude Desktop users — just add the config below. npx handles the rest.

For development:

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

Authentication

Bear stores notes in iCloud via CloudKit. To access them, bcli needs a one-time CloudKit authentication token from Apple Sign-In.

Setup

1. Run bcli auth in a terminal
2. A browser window opens for Apple Sign-In — sign in with your iCloud account
3. Terminal shows "Authenticated successfully." when done
4. Token is saved at ~/.config/bear-cli/auth.json and persists across sessions

Alternative: Authenticate from Claude

The bear_auth MCP tool can trigger authentication directly from a Claude conversation. It opens the same browser flow without leaving your chat.

Headless / SSH environments

If you're running over SSH (no browser available), authenticate with a token directly:

bcli auth --token '<your-ckWebAuthToken>'

Token expiry

If Bear operations start failing with "Not authenticated" or "Auth token expired" errors, re-run bcli auth or use the bear_auth tool.

Claude Desktop Setup

Add this to ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Restart Claude Desktop after editing the config.

For local development, use the built output directly:

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

Available Tools

Tool	Description
bear_get_note	Retrieve a note's full content by ID
bear_list_notes	List notes with optional tag filter and limit
bear_search_notes	Search notes by text query
bear_list_tags	List all tags
bear_create_note	Create a new note with title, body, and tags
bear_edit_note	Append text to an existing note
bear_trash_note	Soft-delete (trash) a note
bear_export_notes	Export notes as Markdown files
bear_auth	Trigger Apple Sign-In authentication

Troubleshooting

"Not authenticated" or "Auth token expired" Run bcli auth in a terminal or use the bear_auth tool.

Claude Desktop can't find the server Check that Node.js is in your PATH. The npx method is recommended — it handles installation automatically.

"bcli binary not found" Run npm install to trigger the postinstall script that downloads bcli.

License

MIT