bear-notes

Bear Notes MCP provides a hybrid, sync-safe access layer for your Bear notes. It exposes a set of read tools that query the Bear database directly for fast, read-only access, and a set of write tools that use Bear's official x-callback-url API to perform changes in a safe, sync-enabled manner. This separation ensures read operations are instantaneous and writes are safe against iCloud sync conflicts. You can ask Claude to search, filter, analyze, tag, and organize notes, as well as create or modify notes via Bear's API.

To use it, install and run the MCP server locally, then configure Claude Desktop to point at the server using the provided host/port or path to the running instance. Once connected, you can invoke natural language prompts like listing recent notes, searching by tag, extracting statistics, or creating and updating notes. The server supports both broad discovery (full-text search, tag browsing, relationships) and targeted actions (create/edit notes, manage tags) via the Bear API for writes and direct database reads for safety and performance.

Prerequisites

• Bear app installed on macOS
• Claude Desktop app
• Node.js 18+ installed

Installation steps

1. Clone the repository and install dependencies:

git clone <repository-url>
cd bear-notes-mcp
npm install

2. Build the project (produces dist/index.js):

npm run build

3. Run or integrate with Claude Desktop:

• Start the MCP server (example):

node dist/index.js

• Add to Claude Desktop configuration (example path): Edit ~/Library/Application Support/Claude/claude_desktop_config.json and include:

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

• Restart Claude Desktop and begin asking Claude about your Bear notes.

Environment variables and configuration tips:

• BEAR_DB_PATH: Override the default Bear database location for reads. Useful if you run a custom Bear database or want to point to a test DB.
• NODE_ENV: Set to 'development' to enable debug logging during development. Remove or set to 'production' in production.
• Writes go through Bear's x-callback-url API for safety; reads are performed directly from the Bear SQLite database for speed. Common issues:
• Ensure Bear is installed and the Bear database path is accessible.
• If writes fail, verify Bear API accessibility and that Bear is running or accessible via x-callback-url.
• After config changes, restart Claude Desktop to pick up the MCP server settings.