bear-mcp

jakeswenson/bear-mcp

3.1

If you are the rightful owner of bear-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

MCP Server for bear is built on bear-query, providing a robust framework for managing model context protocols.

bear-mcp

A read-only Model Context Protocol (MCP) server for Bear notes, built on bear-query. This server allows AI assistants like Claude to search, retrieve, and explore your Bear notes library.

Features

  • Search Notes - Efficient full-text search using Bear's database indices
  • Get Note Details - Direct note lookup by ID without fetching all notes
  • List Tags - Browse all tags in your Bear database
  • Read-Only Access - Safe, non-destructive queries only
  • Fast SQLite Access - Optimized queries with minimal overhead
  • Null-Safe - Properly handles notes with missing content or metadata

Available Tools

search_notes

Search for notes in Bear by title or content with optional filters. Uses Bear's database search capabilities for efficient queries.

Parameters:

  • query (optional): Search text to match against note titles and content. When provided, performs an efficient database search. When omitted, returns recent notes.
  • pinned_only (optional): Only return pinned notes
  • include_trashed (optional): Include trashed notes in results (default: false)
  • include_archived (optional): Include archived notes in results (default: false)
  • limit (optional): Maximum number of results to return (default: 50 for search, 10 for listing)

Examples:

// Search for notes containing "rust programming"
{
  "query": "rust programming",
  "limit": 10
}

// List pinned notes only
{
  "pinned_only": true
}

// Get all notes including archived
{
  "include_archived": true,
  "limit": 100
}

get_note

Get the full content of a specific note by its unique ID. Uses direct database lookup for fast retrieval.

Parameters:

  • note_id (required): The unique identifier (UUID) of the note to retrieve

Example:

{
  "note_id": "ABC123-DEF456-GHI789"
}

Note: This method performs a direct lookup by ID and does not fetch all notes, making it very efficient.

list_tags

List all tags in the Bear database with modification dates.

Parameters: None

Installation

Prerequisites

  • Bear notes app installed on macOS
  • Claude Desktop or another MCP-compatible client

Option 1: Install from crates.io (Recommended)

cargo install bear-mcp

The binary will be installed to ~/.cargo/bin/bear-mcp (which should already be in your PATH if you have Rust installed).

Option 2: Building from Source

# Clone the repository
git clone https://github.com/jakeswenson/bear-mcp
cd bear-mcp

# Build the project
cargo build --release

# The binary will be at target/release/bear-mcp

Configuration

Claude Desktop

Add the server to your Claude Desktop configuration file:

Location: ~/Library/Application Support/Claude/claude_desktop_config.json

If installed via cargo install:

{
  "mcpServers": {
    "bear": {
      "command": "/Users/YOUR_USERNAME/.cargo/bin/bear-mcp"
    }
  }
}

Replace YOUR_USERNAME with your actual username. You can find the exact path by running which bear-mcp in your terminal.

If built from source:

{
  "mcpServers": {
    "bear": {
      "command": "/Users/YOUR_USERNAME/path/to/bear-mcp/target/release/bear-mcp"
    }
  }
}

Replace /Users/YOUR_USERNAME/path/to/bear-mcp with the actual path to your cloned repository.

Environment Variables

The server uses the RUST_LOG environment variable for logging configuration:

{
  "mcpServers": {
    "bear": {
      "command": "/Users/YOUR_USERNAME/.cargo/bin/bear-mcp",
      "env": {
        "RUST_LOG": "info"
      }
    }
  }
}

Log Levels:

  • error - Only errors
  • warn - Warnings and errors
  • info - Informational messages (default)
  • debug - Detailed debugging
  • trace - Very verbose output

Logs are written to stderr and will appear in Claude Desktop's logs.

Usage Examples

Once configured, you can ask Claude to interact with your Bear notes:

  • "Search my Bear notes for anything about Rust"
  • "Show me my pinned notes"
  • "List all my Bear tags"
  • "Get the full content of note ABC123-DEF456-GHI789"
  • "Find notes about machine learning that aren't archived"

How It Works

The server connects directly to Bear's SQLite database in read-only mode:

  • Database Location: ~/Library/Group Containers/9K33E3U3T4.net.shinyfrog.bear/Application Data/database.sqlite
  • Access Mode: SQLITE_OPEN_READ_ONLY with PRAGMA query_only = ON
  • Connection Strategy: Short-lived connections created per-query to avoid locking issues

The server uses the bear-query library which provides:

  • Normalized views of Bear's Core Data structure
  • Efficient search API using database indices
  • Null-safe handling of missing or incomplete data
  • Direct note lookup by ID without fetching all notes

Development

Running in Development

# Run with debug logging
RUST_LOG=debug cargo run

Testing

You can test the server using the MCP Inspector or by piping JSON-RPC messages:

# Example: Call the list_tags tool
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_tags"}}' | cargo run

Architecture

  • src/main.rs - Entry point, sets up logging and stdio transport
  • src/bear_service.rs - MCP server implementation with tool definitions
  • Cargo.toml - Dependencies and build configuration

Key Dependencies

Limitations

  • Read-Only: Cannot create, modify, or delete notes
  • macOS Only: Bear is a macOS/iOS app; this server requires macOS
  • No Real-Time Updates: The server queries the database on-demand without monitoring for changes
  • Bear Must Be Installed: Requires Bear's SQLite database to be present

Troubleshooting

"Failed to initialize Bear database"

  • Ensure Bear is installed and you have at least opened it once
  • Check that the database file exists: ~/Library/Group Containers/9K33E3U3T4.net.shinyfrog.bear/Application Data/database.sqlite
  • Verify you have read permissions on the database file

Server Not Appearing in Claude

  • Check the path in claude_desktop_config.json is correct and absolute
  • Ensure the binary is executable: chmod +x target/release/bear-mcp
  • Restart Claude Desktop after modifying the config
  • Check Claude's logs: ~/Library/Logs/Claude/

Empty Results

  • Verify you have notes in Bear
  • Check if notes are trashed/archived and adjust search parameters accordingly
  • Try list_tags first to confirm database connectivity

License

[Add your license here]

Contributing

[Add contributing guidelines here]

Acknowledgments

  • Built with rmcp - Rust MCP SDK
  • Uses bear-query for database access
  • Inspired by the Model Context Protocol specification