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

• Rust toolchain (1.70+)
• Bear notes app installed on macOS
• Claude Desktop or another MCP-compatible client

Building from Source

# Clone the repository
git clone <your-repo-url>
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

{
  "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/path/to/bear-mcp/target/release/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

• rmcp - Rust MCP SDK
• bear-query - Bear database query library
• tokio - Async runtime
• tracing - Logging and diagnostics
• serde - Serialization framework

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