netologist/mcp-bear-notes

Bear App MCP Server

A Model Context Protocol (MCP) server that provides Claude with access to your Bear App notes. Search, retrieve, and analyze your Bear notes directly from Claude Desktop or any MCP-compatible client.

Features

🔍 Search & Discovery

• Full-text search across all your notes
• Tag-based filtering for organized content
• Title-based search with exact or partial matching
• Recent notes filtering by modification date

💻 Code & Technical Content

• Kubernetes manifest finder - Locate deployment examples, service configs, etc.
• Code example search - Find code snippets by programming language
• Code block extraction - Automatically parse and categorize code blocks
• Technical documentation discovery

📊 Content Analysis

• Word count and content statistics
• Code language detection from fenced code blocks
• Content previews for quick scanning
• Metadata extraction (creation/modification dates)

Installation

Prerequisites

• macOS (Bear App is macOS/iOS only)
• Bear App installed and with some notes
• Python 3.8 or higher
• Claude Desktop (for desktop integration)

Setup Steps

1. Clone or download the server script

   git clone github.com/netologist/mcp-bear-notes
   

2. Create a virtual environment

   uv install
   source .venv/bin/activate
   

3. Test the server

   uv run python main.py
   

Claude Desktop Integration

Configuration File Location

Edit your Claude Desktop configuration file:

~/Library/Application Support/Claude/claude_desktop_config.json

Add MCP Server Configuration

{
  "mcpServers": {
    "bear-notes": {
      "command": "/full/path/to/mcp-bear-notes/.venv/bin/python",
      "args": ["/full/path/to/mcp-bear-notes/main.py"],
      "env": {
        "PYTHONPATH": "/full/path/to/mcp-bear-notes/.venv/lib/python3.13/site-packages"
      }
    }
  }
}

Important: Replace /full/path/to/ with your actual file paths.

Restart Claude Desktop

Close and reopen Claude Desktop to load the MCP server.

Usage Examples

Once integrated with Claude Desktop, you can use natural language to interact with your Bear notes:

Basic Search

"Search my Bear notes for Docker examples"
"Find notes about Python APIs"
"Show me my recent notes from this week"

Technical Content

"Find my Kubernetes deployment manifests"
"Look for JavaScript code examples in my notes"
"Show me notes with YAML configurations"

Specific Retrieval

"Get the note titled 'Development Setup'"
"Find notes tagged with 'work'"
"Show me all my available tags"

Available Tools

search_bear_notes(query, tag, limit)

Search notes by content and tags.

• query: Text to search for
• tag: Filter by specific tag (without #)
• limit: Max results (default: 20)

get_bear_note(note_id)

Retrieve a specific note by its unique ID.

• note_id: Bear note's unique identifier

find_kubernetes_examples(resource_type)

Find Kubernetes-related content.

• resource_type: K8s resource (deployment, service, etc.)

find_code_examples(language, topic, limit)

Search for code examples.

• language: Programming language
• topic: Code topic/domain
• limit: Max results (default: 15)

find_notes_by_title(title_query, exact_match)

Search notes by title.

• title_query: Title text to search
• exact_match: Exact or partial matching

get_recent_notes(days, limit)

Get recently modified notes.

• days: How many days to look back (default: 7)
• limit: Max results (default: 20)

list_bear_tags()

List all tags found in your notes.

Bear Database Information

The server reads from Bear's SQLite database located at:

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

Database Access Notes

• Read-only access - The server never modifies your notes
• No authentication required - Uses direct SQLite access
• Performance - Database queries are optimized for speed
• Safety - Only accesses non-trashed notes

Troubleshooting

Common Issues

Server won't start

• Check Python path in configuration
• Verify virtual environment activation
• Ensure fastmcp is installed

No notes found

• Verify Bear database path exists
• Check that Bear App has been opened at least once
• Confirm notes aren't in trash

Claude Desktop integration fails

• Validate JSON syntax in config file
• Check file paths are absolute, not relative
• Restart Claude Desktop after configuration changes

Permission denied errors

• Ensure script has execute permissions: chmod +x main.py
• Check Bear database file permissions

Debug Mode

Run the server directly to see debug output:

python main.py

Log Files

Check Claude Desktop logs for MCP server errors:

~/Library/Logs/Claude/

Security & Privacy

• Local-only: All data stays on your machine
• Read-only: Server never modifies your notes
• No network: No external connections required
• Open source: Full transparency of operations

Contributing

Contributions welcome! Areas for improvement:

• Additional search filters
• Export functionality
• Note creation capabilities
• iOS Shortcuts integration
• Performance optimizations

License

MIT License - See LICENSE file for details.

Changelog

v1.0.0

• Initial release
• Basic search and retrieval functions
• Kubernetes and code example finders
• Claude Desktop integration
• Tag listing and filtering

Support

For issues and questions:

1. Check the troubleshooting section
2. Review Claude Desktop MCP documentation
3. Open an issue on GitHub
4. Check Bear App forums for database-related questions

Note: This is an unofficial tool and is not affiliated with Bear App or Anthropic. Use at your own discretion.