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