# 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.