bear-notes-mcp

bejaminjones/bear-notes-mcp

3.3

If you are the rightful owner of bear-notes-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 henry@mcphub.com.

The Bear MCP Server is a Model Context Protocol server that integrates with the Bear notes application, providing comprehensive access to notes through a hybrid sync-safe approach.

Bear MCP Server

A Model Context Protocol (MCP) server that provides Claude with comprehensive access to your Bear notes using a hybrid sync-safe approach - combining direct database reads with Bear's API for writes.

🔄 Sync-Safe Hybrid Mode: All operations now work safely with iCloud sync!

⚠️ Disclaimer

This tool uses a hybrid approach: direct database reads + Bear API writes. While comprehensive safety measures are implemented:

  • Read operations access Bear's database directly (read-only, safe)
  • Write operations use Bear's official API (sync-safe)
  • The tool is not affiliated with Bear's developers
  • Always maintain regular Bear backups as good practice

🚀 Quick Start (5 minutes)

Prerequisites

  • Bear app installed on macOS
  • Claude Desktop app
  • Node.js 18+ installed

Installation

  1. Clone and setup:
git clone <repository-url>
cd bear-notes-mcp
npm install
npm run build
  1. Add to Claude Desktop configuration: Edit ~/Library/Application Support/Claude/claude_desktop_config.json:
{
  "mcpServers": {
    "bear": {
      "command": "node",
      "args": ["/path/to/bear-notes-mcp/dist/index.js"],
      "env": {}
    }
  }
}
  1. Start using:
  • Restart Claude Desktop
  • Ask Claude: "What Bear notes do I have?"
  • Begin managing your notes with natural language!

✨ What You Can Do

📖 Read Operations (26 tools) - ✅ ACTIVE

  • Search & Discovery: Full-text search, find similar notes, get suggestions
  • Organization: Browse by tags, analyze note relationships, get statistics
  • Content Analysis: Extract metadata, analyze attachments, find patterns
  • Advanced Queries: Complex filtering, date ranges, content criteria

✏️ Write Operations (6 tools) - ✅ ACTIVE (Sync-Safe)

  • Create Notes: ✅ Via Bear API (sync-safe)
  • Edit Notes: ✅ Via Bear API (sync-safe)
  • Organize: ✅ Via Bear API (sync-safe)
  • Tag Management: ✅ Via Bear API (sync-safe)
  • Hashtag Parsing: ✅ Via Bear API (sync-safe)

How it works: Uses Bear's x-callback-url API for writes, database for reads!

🛡️ Safety Features

  • Hybrid Architecture: Database reads + API writes for maximum safety
  • iCloud Sync Safe: All write operations use Bear's API
  • Conflict Detection: Prevents overwriting concurrent changes
  • Tag Validation: Automatic tag sanitization with warnings
  • Error Handling: Robust error management for all operations

📊 Capabilities Overview

CategoryToolsStatusKey Features
Basic Operations6✅ ActiveGet notes, search, browse tags, database stats
Advanced Search8✅ ActiveFull-text search, similarity matching, complex queries
Analytics6✅ ActiveContent analysis, relationship mapping, usage patterns
Metadata6✅ ActiveFile attachments, content structure, organization insights
Write Operations6✅ ActiveSync-safe via Bear API - full write capability restored!

🔧 Configuration

Database Location

The server automatically finds your Bear database at:

~/Library/Group Containers/9K33E3U3T4.net.shinyfrog.bear/Application Data/database.sqlite

Environment Variables

  • BEAR_DB_PATH: Override default database location (for reads)
  • NODE_ENV: Set to 'development' for debug logging

📚 Usage Examples

Basic Note Management

"Show me my recent notes"
"Find all notes tagged with 'project'"  
"Create a new note about today's meeting"
"Search for notes containing 'API documentation'"
"Update my project notes with the latest status"

Advanced Operations

"Analyze my note-taking patterns this month"
"Find notes similar to my current project"
"Show me notes with attachments"
"What are my most-used tags?"

Organization & Cleanup

"Archive old notes from last year"
"Find duplicate or similar notes"
"Show me notes that might need better tags"
"Duplicate this note with a new title"
"Add tags to organize my notes better"

🛡️ Safety & Best Practices

⚠️ Safety Guidelines

  1. Bear can run during operations - Write operations use Bear's API safely
  2. Automatic tag validation - Tags are sanitized with warnings
  3. iCloud sync compatible - No conflicts or sync issues
  4. Keep Bear updated - Ensure API compatibility

💡 Best Practices

  • Read operations are instant - direct database access
  • Write operations work with Bear running or closed
  • Tag warnings show when tags are auto-corrected
  • Use specific search terms for better results
  • Archive notes instead of deleting when possible

🏷️ Tag Formatting Guidelines

✅ RECOMMENDED TAG FORMATS:

  • Simple tags: work, personal, urgent, meeting
  • Nested categories: work/projects, personal/health, study/math
  • Time-based: 2024, january, q1
  • Project codes: proj001, alpha, beta

❌ AVOID THESE FORMATS (auto-corrected):

  • Hyphens: project-alpha → becomes projectalpha
  • Spaces: work meeting → becomes workmeeting
  • Mixed case: ProjectAlpha → becomes projectalpha

🔧 Automatic Tag Sanitization: The server automatically validates and sanitizes all tags:

  • Lowercase only: Project → project
  • No spaces: tag name → tagname
  • No hyphens: project-alpha → projectalpha
  • No commas: tag,name → tagname
  • ✅ Forward slashes preserved: project/alpha → project/alpha (for nested tags)

Tag warnings are returned when tags are modified, so you'll know exactly what changes were made.

🏗️ REFACTORED SERVICE ARCHITECTURE

✅ Completely refactored from monolith to modern service-oriented architecture!

Transformation Overview

We've completely rebuilt the system from a 2,589-line monolithic BearService into a modern, testable, service-oriented architecture:

🔧 Service-Based Design

  • 7 specialized services with clear responsibilities
  • Dependency injection for testability and flexibility
  • Interface-driven development for maintainability
  • 384 comprehensive tests across all services

🛡️ Hybrid Sync-Safe Architecture

  • Read Operations: Direct SQLite database access for maximum performance
  • Write Operations: Bear's x-callback-url API for sync safety
  • Perfect coordination using ZUNIQUEIDENTIFIER bridge

📊 Quality & Performance

  • 100% TypeScript with strict type checking
  • Comprehensive error handling and validation
  • Multi-level caching for performance optimization
  • Structured logging and health monitoring

Service Architecture

ServiceContainer (Dependency Injection)
├── DatabaseService      (SQLite operations & connection management)
├── CacheService        (Performance optimization & intelligent caching)
├── LoggingService      (Structured logging with Winston)
├── HealthService       (System monitoring & health checks)
├── ValidationService   (Input validation & data sanitization)
├── NoteService         (Note CRUD & lifecycle management)
├── SearchService       (Advanced search & content discovery)
└── TagService          (Tag management & organization)

Why This Architecture Works

The Problem: Monolithic code was hard to test, maintain, and extend.

The Solution: Service-oriented architecture with clear separation of concerns.

The Result:

  • ✅ Maintainable code - Clear service boundaries and responsibilities
  • ✅ 100% test coverage - 384 tests across all services
  • ✅ Type safety - Eliminated 50+ any types
  • ✅ Performance optimized - Multi-level caching and query optimization
  • ✅ Production ready - Comprehensive logging, monitoring, and error handling
  • ✅ Sync-safe operations - Hybrid approach eliminates iCloud conflicts

Current Status

  • ✅ All read operations - Direct database access (26 tools)
  • ✅ All write operations - Sync-safe Bear API (6 tools)
  • ✅ Full feature parity - Everything works as designed
  • ✅ iCloud sync compatible - No conflicts or issues
  • ✅ Duplicate title fix - Notes display titles correctly (no duplication)

🙏 Thanks to Bear Team

Special thanks to Danilo from the Bear team who provided the key insight that led to this solution!

🤝 Contributing & Community

The iCloud sync challenge has been solved! 🎉 Now we're focused on making this the best Bear integration possible. Whether you're a:

  • macOS/iOS developer with API experience
  • Database expert familiar with SQLite optimization
  • Bear power user with workflow insights
  • Developer wanting to contribute to MCP ecosystem

Your contribution can help thousands of Bear users get even more from their AI assistants!

Current Priorities

  1. 🚀 Add new features - More ways to analyze and work with notes
  2. 📖 Improve documentation - Help others understand and contribute
  3. 🧪 Expand test coverage - Ensure reliability across Bear versions
  4. ⚡ Performance optimization - Make operations even faster

Quick Ways to Help

  • ⭐ Star the repo if you find it useful
  • 🐛 Report issues you encounter
  • 💡 Share ideas for new features or solutions
  • 🔗 Spread the word to developers who might help
  • 📝 Contribute documentation improvements

Together, we can build the most powerful Bear integration for AI assistants!

🔍 All Available Tools

📖 Read Operations (26 tools) - ✅ ACTIVE

Basic Operations (6 tools)

  • get_database_stats - Overview of your Bear database
  • get_notes - List notes with filtering options
  • get_note_by_id - Get specific note by ID
  • get_note_by_title - Find note by exact title
  • get_tags - List all tags with usage counts
  • get_notes_by_tag - Find notes with specific tag

Advanced Search (8 tools)

  • get_notes_advanced - Complex filtering and sorting
  • get_notes_with_criteria - Multi-criteria search
  • search_notes_fulltext - Full-text search with relevance scoring
  • get_search_suggestions - Auto-complete for searches
  • find_similar_notes - Content similarity matching
  • get_related_notes - Find related notes by tags and content
  • get_recent_notes - Recently created or modified notes
  • get_note_counts_by_status - Statistics by note status

Analytics & Insights (6 tools)

  • get_note_analytics - Comprehensive note statistics
  • analyze_note_metadata - Content pattern analysis
  • get_notes_with_metadata - Filter by content characteristics
  • get_file_attachments - File attachment management
  • get_tag_hierarchy - Tag relationship analysis
  • get_tag_analytics - Tag usage patterns

Content Analysis (6 tools)

  • analyze_tag_relationships - Tag optimization suggestions
  • get_tag_usage_trends - Tag usage over time
  • search_notes_regex - Pattern matching (when available)
  • Advanced content categorization
  • Link and reference analysis
  • Writing pattern insights
✏️ Write Operations (6 tools) - ✅ ACTIVE (Sync-Safe)

Note Management - SYNC-SAFE VIA BEAR API

  • create_note - ✅ Create new notes with tags and content
  • update_note - ✅ Update existing notes safely
  • duplicate_note - ✅ Create copies of existing notes
  • archive_note - ✅ Archive/unarchive notes
  • trigger_hashtag_parsing - ✅ Force hashtag reprocessing
  • batch_trigger_hashtag_parsing - ✅ Bulk hashtag processing

✅ All operations are now sync-safe:

  • Uses Bear's x-callback-url API for all writes
  • No iCloud sync conflicts or data corruption
  • Respects Bear's internal sync coordination
  • Full write functionality restored

Perfect integration between database reads and API writes!

🔧 Troubleshooting

Common Issues

"Database not found" error:

  • Verify Bear is installed and has been opened at least once
  • Check database path: ~/Library/Group Containers/9K33E3U3T4.net.shinyfrog.bear/Application Data/

"Permission denied" error:

  • Ensure Claude Desktop has necessary file system permissions
  • Check that the database file is readable

Write operations not working:

  • Ensure Bear app is installed and has been opened at least once
  • Check that Bear's x-callback-url functionality is enabled
  • Try opening Bear manually to verify it's working

Slow performance:

  • Large databases (10,000+ notes) may take longer for reads
  • Use specific search terms instead of broad queries
  • Consider using pagination with limit parameters

Getting Help

  1. Check the
  2. Review
  3. Enable debug logging with NODE_ENV=development
  4. Test Bear's API directly: open "bear://x-callback-url/create?title=Test"

📈 Performance

  • Read operations: Instant (direct database access)
  • Write operations: 1-2 seconds (Bear API processing)
  • Large databases: Tested with 10,000+ notes
  • Memory usage: ~50MB typical, ~100MB for complex operations
  • Concurrent operations: Read operations can run simultaneously
  • API operations: Processed through Bear's URL scheme

📄 License

MIT License - see file for details.

Made with ❤️ for the Bear community