Content
# bear-mcp
A read-only Model Context Protocol (MCP) server for [Bear](https://bear.app) notes, built on [bear-query](https://crates.io/crates/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:**
```json
// 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:**
```json
{
"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)
```bash
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
```bash
# 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:**
```json
{
"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:**
```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:
```json
{
"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](https://crates.io/crates/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
```bash
# 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:
```bash
# 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`](https://crates.io/crates/rmcp) - Rust MCP SDK
- [`bear-query`](https://crates.io/crates/bear-query) - Bear database query library
- [`tokio`](https://tokio.rs) - Async runtime
- [`tracing`](https://tracing.rs) - Logging and diagnostics
- [`serde`](https://serde.rs) - 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](https://github.com/modelcontextprotocol/rust-sdk) - Rust MCP SDK
- Uses [bear-query](https://crates.io/crates/bear-query) for database access
- Inspired by the Model Context Protocol specification
