Bear

This MCP server lets you access and manage Bear notes through a hybrid, sync-safe workflow. You read directly from Bear’s database for fast access and perform writes via Bear’s official API, ensuring safe synchronization with iCloud. This setup enables powerful natural-language interactions with your Bear notes while keeping data safe and consistent.

How to use

Install and run the MCP server, then connect it to your MCP client to start querying and managing your Bear notes. You can perform read operations directly from the Bear database for fast results and execute write operations through Bear's API to keep your notes in sync with iCloud.

Practical usage patterns you can try after the server is running: search your notes, browse by tag, analyze note relationships, and create or update notes via natural language commands. Writes happen through the Bear API to ensure proper synchronization, while reads pull from Bear’s local data for speed.

How to install

Prerequisites you need on your machine:

• Bear app installed on macOS

• Claude Desktop app

• Node.js 18 or newer

Step 1 — clone and set up the MCP server code

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

Step 2 — configure the MCP server in Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` to add the Bear MCP server configuration.
```json
{
  "mcpServers": {
    "bear": {
      "command": "node",
      "args": ["/path/to/bear-notes-mcp/dist/index.js"],
      "env": {}
    }
  }
}

Configuration and maintenance

The MCP server looks for Bear’s database at the default Bear data location and exposes read/write capabilities through the Hybrid Sync-Safe architecture. You can override the read database location with an environment variable if needed.

# Default database location used by the server
~/Library/Group Containers/9K33E3U3T4.net.shinyfrog.bear/Application Data/database.sqlite

# Optional override (read operations)
BEAR_DB_PATH=/path/to/custom/database.sqlite
NODE_ENV=production

Safety, best practices, and tag handling

• Read operations access Bear’s database directly for speed and safety. They are read-only.

• Write operations go through Bear’s x-callback-url API to synchronize changes safely with iCloud.

• Tags are automatically sanitized with warnings when changes are made. Use consistent tag formats to avoid unwanted auto-corrections.

• Enable debug logging during troubleshooting by setting NODE_ENV to development.

Troubleshooting and tips

• If you get a database not found error, ensure Bear is installed and opened at least once, and verify the database path exists.

• If you encounter permission issues, confirm Claude Desktop has the necessary file system permissions and that the Bear database file is readable.

• For slow performance on very large Bear databases, use precise search terms and consider pagination where supported.

Performance expectations

Read operations are near-instant due to direct database access. Write operations typically complete in 1–2 seconds asBear processes the request via its API. Memory usage is typically around 50 MB, rising with more complex queries.

Available tools

read_notes

Retrieve notes with filtering options, tags, and stats for analysis and discovery.

search_notes_fulltext

Perform comprehensive full-text searches with relevance scoring across notes.

get_note_by_id

Fetch a specific note by its unique identifier.

create_note

Create a new note via the Bear API with tags and content.

update_note

Update an existing note safely through the Bear API.

archive_note

Archive or unarchive a note via the API.

trigger_hashtag_parsing

Force reprocessing of hashtags for notes.

batch_trigger_hashtag_parsing

Perform hashtag parsing on multiple notes in one operation.