Bear Notes MCP Server

A Model Context Protocol (MCP) server for Bear Notes that provides semantic search, AI summarization, and note relationship discovery capabilities.

🐻 What is this?

This MCP server allows AI assistants and other MCP clients to interact with your Bear Notes database, providing:

• 📖 Note Access: Read individual notes and browse your entire collection
• 🔍 Search & Discovery: Find notes by content with intelligent search
• 🔗 Relationship Analysis: Discover related notes and topics (planned)
• 🤖 AI Integration: Summarize and analyze notes with local AI models (planned)
• ⚡ Real-time Updates: Automatically refresh when notes change

🏗️ Architecture

The server is built with a modular architecture:

• Configuration System: YAML-based config with environment overrides
• Database Interface: Read-only access to Bear's SQLite database
• MCP Protocol: Full implementation with resources and tools
• Monitoring: Real-time database change detection
• Extensible Design: Ready for semantic analysis and AI features

🚀 Installation

Prerequisites

• Python 3.11+
• uv (recommended package manager)
• Bear Notes 2.x (installed on macOS)
• Bear Database Access: Ensure Bear has been launched at least once

Install with uv (Recommended)

# Clone the repository
git clone <repository-url>
cd bear-mcp-python

# Install with uv (creates virtual environment automatically)
uv sync

# Install with development dependencies
uv sync --extra dev

Alternative: Install with pip

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in development mode
pip install -e .

# Install development dependencies (optional)
pip install -e ".[dev]"

⚙️ Configuration

The server will auto-detect your Bear database, but you can customize settings:

# Create default configuration
uv run bear-mcp-cli create-config --output config/config.yaml

# Edit configuration as needed
# Key settings:
# - bear_db.path: Path to Bear database (auto-detected if null)
# - logging.level: Logging verbosity (DEBUG, INFO, WARNING, ERROR)
# - mcp_server.max_resources: Limit on resources returned

Environment Variables

Override any configuration with environment variables using the BEAR_MCP_ prefix:

export BEAR_MCP_LOGGING_LEVEL=DEBUG
export BEAR_MCP_BEAR_DB_PATH="/path/to/custom/database.sqlite"
export BEAR_MCP_MCP_SERVER_MAX_RESOURCES=500

🧪 Testing & Development

CLI Tools

The project includes CLI tools for testing and development:

Find Bear Database

# Locate Bear database files on your system
uv run bear-mcp-cli find-db

Test Database Connection

# Test connection to Bear database and show statistics
uv run bear-mcp-cli test-db

List Notes

# List recent notes (default: 10 notes)
uv run bear-mcp-cli list-notes

# List more notes with options
uv run bear-mcp-cli list-notes --limit 25

# Include trashed and archived notes
uv run bear-mcp-cli list-notes --include-trashed --include-archived --limit 50

Create Configuration

# Create default configuration file
uv run bear-mcp-cli create-config

# Create in custom location
uv run bear-mcp-cli create-config --output ~/.bear-mcp/config.yaml

# Force overwrite existing file
uv run bear-mcp-cli create-config --force

Verify Installation

# 1. Check if Bear database can be found
uv run bear-mcp-cli find-db

# 2. Test database connection
uv run bear-mcp-cli test-db

# 3. List a few notes to verify data access
uv run bear-mcp-cli list-notes --limit 5

Expected output for a working setup:

INFO     Found database                         path=/Users/.../database.sqlite
INFO     Database connection successful
INFO     Database stats                         total_notes=150 active_notes=145 ...

🔌 MCP Server Usage

With MCP Clients

Start the MCP server for use with MCP clients:

# Run the MCP server (stdio mode)
uv run bear-mcp

The server provides these MCP resources:

• notes://all - JSON list of all active notes with metadata
• note:///{note_id} - Individual note content in Markdown format

And these MCP tools:

• get_note - Retrieve full content of a specific note
• search_notes - Search notes by title and content
• list_notes - List notes with filtering options
• get_database_stats - Get database statistics

Integration Examples

Claude Desktop

Add to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "bear-notes": {
      "command": "uv",
      "args": ["run", "bear-mcp"],
      "cwd": "/path/to/bear-mcp-python",
      "env": {
        "BEAR_MCP_LOGGING_LEVEL": "INFO"
      }
    }
  }
}

Other MCP Clients

The server implements the standard MCP protocol over stdio, so it should work with any MCP-compatible client.

📁 Project Structure

bear_mcp/
├── config/          # Configuration management
├── bear_db/         # Bear database interface
├── mcp_server/      # MCP protocol implementation  
├── semantic/        # Semantic analysis (Phase 2)
├── ai/              # AI integration (Phase 3)
├── main.py          # Server entry point
├── cli.py           # CLI utilities
└── utils.py         # Utility functions

config/
└── config.yaml      # Default configuration

tests/               # Test suite (Phase 5)

🐛 Troubleshooting

Bear Database Not Found

# Check if Bear is installed and has been run
uv run bear-mcp-cli find-db

# If no database found:
# 1. Launch Bear.app at least once
# 2. Create a test note
# 3. Try finding the database again

Permission Issues

# Bear database is read-only by design
# If you get permission errors:
# 1. Make sure Bear.app is not running
# 2. Check file permissions on the database
# 3. Try running with different user permissions

Connection Timeouts

# If database connections timeout:
# 1. Check if Bear is actively syncing
# 2. Increase timeout in configuration:
export BEAR_MCP_BEAR_DB_TIMEOUT=60.0

No Notes Returned

# If no notes are returned:
# 1. Check that notes exist in Bear
# 2. Verify notes are not all trashed/archived
uv run bear-mcp-cli list-notes --include-trashed --include-archived

uv Installation Issues

# If uv is not installed, install it first:
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or using pip:
pip install uv

# Then run uv sync to set up the project
uv sync

🗺️ Development Roadmap

✅ Phase 1: Foundation (Complete)

• Project setup and configuration
• Bear database interface
• Basic MCP server with resources and tools
• Database monitoring and caching

🔄 Phase 2: Semantic Analysis (Planned)

• Sentence transformer embeddings
• ChromaDB vector storage
• Semantic similarity search
• Related notes discovery

🤖 Phase 3: AI Integration (Planned)

• Ollama integration for local AI
• Note summarization
• Content analysis and insights
• Intelligent tagging

⚡ Phase 4: Advanced Features (Planned)

• Enhanced MCP tools
• Performance optimization
• Caching improvements
• Advanced search capabilities

🧪 Phase 5: Testing & Polish (Planned)

• Comprehensive test suite
• Documentation and guides
• Deployment tools
• Performance benchmarks

🤝 Contributing

This project is in active development. Current focus is on Phase 2 implementation.

Development Setup with uv

# Install with development dependencies
uv sync --extra dev

# Run code formatting
uv run black bear_mcp/
uv run ruff check bear_mcp/

# Run type checking  
uv run mypy bear_mcp/

# Run tests (when available)
uv run pytest

Development Setup with pip

# Install with development dependencies
pip install -e ".[dev]"

# Run code formatting
black bear_mcp/
ruff check bear_mcp/

# Run type checking  
mypy bear_mcp/

# Run tests (when available)
pytest

📄 License

[Add your license here]

🙏 Acknowledgments

• Bear Notes - The excellent note-taking app this server connects to
• Model Context Protocol - The protocol that makes this integration possible
• Anthropic - For Claude and MCP development
• uv - Fast Python package manager

---

Note: This server provides read-only access to your Bear Notes database. It never modifies your notes or database.