https://github.com/netologist/mcp-bear-notes
MCP Server for My Bear App Notes
https://github.com/netologist/mcp-bear-notes
Last synced: 3 months ago
JSON representation
MCP Server for My Bear App Notes
- Host: GitHub
- URL: https://github.com/netologist/mcp-bear-notes
- Owner: netologist
- Created: 2025-06-20T06:31:07.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2025-06-20T06:31:26.000Z (4 months ago)
- Last Synced: 2025-06-29T11:09:12.417Z (3 months ago)
- Language: Python
- Size: 17.6 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 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**
```bash
git clone github.com/netologist/mcp-bear-notes
```
2. **Create a virtual environment**
```bash
uv install
source .venv/bin/activate
```
4. **Test the server**
```bash
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
```json
{
"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:
```bash
python main.py
```
### Log Files
Check Claude Desktop logs for MCP server errors:
```bash
~/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.