Bear MCP Server

Provides direct access to your Bear notes database for comprehensive note management, bypassing standard API limitations.

A Model Context Protocol (MCP) server that provides Claude with comprehensive access to your Bear notes using ahybrid 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:

- 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

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

git clone <repository-url> cd bear-notes-mcp npm install npm run build

- 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": {} } } }

- Restart Claude Desktop
- Ask Claude: "What Bear notes do I have?"
- Begin managing your notes with natural language!

- 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!

- 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

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"

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

- Read operationsare instant - direct database access
- Write operationswork with Bear running or closed
- Tag warningsshow when tags are auto-corrected
- Use specific search terms for better results
- Archive notes instead of deleting when possible

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

- Hyphens:project-alpha→ becomesprojectalpha
- Spaces:work meeting→ becomesworkmeeting
- Mixed case:ProjectAlpha→ becomesprojectalpha

🔧 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 warningsare 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 a2,589-line monolithic BearServiceinto amodern, testable, service-oriented architecture:

- 7 specialized serviceswith clear responsibilities
- Dependency injectionfor testability and flexibility
- Interface-driven developmentfor maintainability
- 384 comprehensive testsacross all services

- Read Operations: Direct SQLite database access for maximum performance
- Write Operations: Bear's x-callback-url API for sync safety
- Perfect coordinationusingZUNIQUEIDENTIFIERbridge

- 100% TypeScriptwith strict type checking
- Comprehensive error handlingand validation
- Multi-level cachingfor performance optimization
- Structured loggingand health monitoring

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.

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

- ✅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)

Special thanks toDanilo from the Bear teamwho provided the key insight that led to this solution!

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

- macOS/iOS developerwith API experience
- Database expertfamiliar with SQLite optimization
- Bear power userwith workflow insights
- Developerwanting to contribute to MCP ecosystem

Your contribution can help thousands of Bear users get even more from their AI assistants!
- 🚀Add new features- More ways to analyze and work with notes
- 📖Improve documentation- Help others understand and contribute
- 🧪Expand test coverage- Ensure reliability across Bear versions
- ⚡Performance optimization- Make operations even faster

- ⭐Star the repoif you find it useful
- 🐛Report issuesyou encounter
- 💡Share ideasfor new features or solutions
- 🔗Spread the wordto developers who might help
- 📝Contribute documentationimprovements

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

- 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

- 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

- 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

- 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

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

- 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!

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

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

- 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

- Large databases (10,000+ notes) may take longer for reads
- Use specific search terms instead of broad queries
- Consider using pagination withlimitparameters
- Check thetroubleshooting guide
- Reviewcommon usage patterns
- Enable debug logging withNODE_ENV=development
- Test Bear's API directly:open "bear://x-callback-url/create?title=Test"

MIT License - seeLICENSEfile for details.

A simple notes system for Itemit, built with TypeScript.