by bejaminjones
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!
This tool uses a hybrid approach: direct database reads + Bear API writes. While comprehensive safety measures are implemented:
git clone <repository-url> cd bear-notes-mcp npm install npm run build
~/Library/Application Support/Claude/claude_desktop_config.json:*Configuration content*
How it works: Uses Bear's x-callback-url API for writes, database for reads!
| Category | Tools | Status | Key Features |
|---|---|---|---|
| Basic Operations | 6 | ✅ Active | Get notes, search, browse tags, database stats |
| Advanced Search | 8 | ✅ Active | Full-text search, similarity matching, complex queries |
| Analytics | 6 | ✅ Active | Content analysis, relationship mapping, usage patterns |
| Metadata | 6 | ✅ Active | File attachments, content structure, organization insights |
| Write Operations | 6 | ✅ Active | Sync-safe via Bear API - full write capability restored! |
The server automatically finds your Bear database at:
~/Library/Group Containers/9K33E3U3T4.net.shinyfrog.bear/Application Data/database.sqlite
BEAR_DB_PATH: Override default database location (for reads)NODE_ENV: Set to 'development' for debug logging"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"
"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?"
"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"
✅ RECOMMENDED TAG FORMATS:
work, personal, urgent, meetingwork/projects, personal/health, study/math2024, january, q1proj001, alpha, beta❌ AVOID THESE FORMATS (auto-corrected):
project-alpha → becomes projectalphawork meeting → becomes workmeetingProjectAlpha → becomes projectalpha🔧 Automatic Tag Sanitization:
The server automatically validates and sanitizes all tags:
Project → projecttag name → tagnameproject-alpha → projectalphatag,name → tagnameproject/alpha → project/alpha (for nested tags)Tag warnings are returned when tags are modified, so you'll know exactly what changes were made.
✅ Completely refactored from monolith to modern service-oriented architecture!
We've completely rebuilt the system from a 2,589-line monolithic BearService into a modern, testable, service-oriented architecture:
🔧 Service-Based Design
🛡️ Hybrid Sync-Safe Architecture
ZUNIQUEIDENTIFIER bridge📊 Quality & Performance
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)
The Problem: Monolithic code was hard to test, maintain, and extend.
The Solution: Service-oriented architecture with clear separation of concerns.
The Result:
any typesSpecial thanks to Danilo from the Bear team who provided the key insight that led to this solution!
The iCloud sync challenge has been solved! 🎉 Now we're focused on making this the best Bear integration possible. Whether you're a:
Your contribution can help thousands of Bear users get even more from their AI assistants!
Together, we can build the most powerful Bear integration for AI assistants!
📖 Read Operations (26 tools) - ✅ ACTIVE
get_database_stats - Overview of your Bear databaseget_notes - List notes with filtering optionsget_note_by_id - Get specific note by IDget_note_by_title - Find note by exact titleget_tags - List all tags with usage countsget_notes_by_tag - Find notes with specific tagget_notes_advanced - Complex filtering and sortingget_notes_with_criteria - Multi-criteria searchsearch_notes_fulltext - Full-text search with relevance scoringget_search_suggestions - Auto-complete for searchesfind_similar_notes - Content similarity matchingget_related_notes - Find related notes by tags and contentget_recent_notes - Recently created or modified notesget_note_counts_by_status - Statistics by note statusget_note_analytics - Comprehensive note statisticsanalyze_note_metadata - Content pattern analysisget_notes_with_metadata - Filter by content characteristicsget_file_attachments - File attachment managementget_tag_hierarchy - Tag relationship analysisget_tag_analytics - Tag usage patternsanalyze_tag_relationships - Tag optimization suggestionsget_tag_usage_trends - Tag usage over timesearch_notes_regex - Pattern matching (when available)✏️ Write Operations (6 tools) - ✅ ACTIVE (Sync-Safe)
create_note - ✅ Create new notes with tags and contentupdate_note - ✅ Update existing notes safelyduplicate_note - ✅ Create copies of existing notesarchive_note - ✅ Archive/unarchive notestrigger_hashtag_parsing - ✅ Force hashtag reprocessingbatch_trigger_hashtag_parsing - ✅ Bulk hashtag processing✅ All operations are now sync-safe:
Perfect integration between database reads and API writes!
"Database not found" error:
~/Library/Group Containers/9K33E3U3T4.net.shinyfrog.bear/Application Data/"Permission denied" error:
Write operations not working:
Slow performance:
limit parametersNODE_ENV=developmentopen "bear://x-callback-url/create?title=Test"MIT License - see LICENSE file for details.
Made with ❤️ for the Bear community
1 contributor