README.md•6.41 kB
# Bear MCP Server
An MCP (Model Context Protocol) server for integrating Bear Note Taking App with Claude Desktop. This server allows Claude to read, create, and search your Bear notes directly.
## ✨ Features (v4.0.2)
**Full data retrieval capabilities:**
- 🔍 **Search notes** and get complete results with metadata
- 🏷️ **Retrieve all tags** from your Bear database
- 📖 **Read note content** for analysis and summarization
- ✏️ **Create notes** and get their IDs back
- 📝 **Add text** to existing notes
- ✅ **Test setup** with comprehensive status checking
## ⚠️ Current Limitations & Usage Guidelines
### Browser Window Behavior
**Expected**: Brief browser windows may appear during search/tags operations due to Bear's callback system.
- Windows are automatically minimized and moved off-screen
- Auto-close within 1-2 seconds in most cases
- **Safe to manually close** if they persist
- **Focus is returned** to your original window automatically
### Search Reliability
**Success Rate**: ~80-90% of searches work reliably
- **Occasional timeouts** may occur (20-second limit)
- **Simple terms** work better than complex queries
- **Retry once** if a search times out
- **Single words** tend to be more reliable than phrases
### Best Practices
✅ **Recommended Usage**:
```
Search my Bear notes for "project"
Get all my Bear tags
Create a note titled "Meeting Notes" with today's agenda
Add "Action item: Follow up" to my "Weekly Review" note
```
⚠️ **If Issues Occur**:
- **Timeouts**: Wait a moment and retry the same search
- **Browser windows**: Safe to close manually if they don't auto-close
- **No results**: Try simpler/broader search terms
- **Setup issues**: Use `check_bear_setup` to diagnose
## Available Tools
| Tool | Functionality | Reliability | Notes |
|------|---------------|-------------|-------|
| `create_note` | Creates new notes | ✅ Excellent | Always works, returns ID |
| `add_text` | Adds text to notes | ✅ Excellent | Reliable text addition |
| `check_bear_setup` | Tests configuration | ✅ Excellent | Diagnostic tool |
| `search_notes` | Searches notes | ⚠️ Good | ~80-90% success, may timeout |
| `get_tags` | Lists all tags | ⚠️ Good | Usually works, brief popup |
| `get_note` | Retrieves note content | ⚠️ Good | Works well with valid IDs |
## Installation
1. Clone the repository:
```bash
git clone https://github.com/philgetzen/bear-mcp.git
cd bear-mcp
```
2. Install dependencies:
```bash
npm install
```
3. Build the project:
```bash
npm run build
```
## Configuration in Claude Desktop
Add the server to your Claude Desktop configuration file:
### macOS
Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"bear": {
"command": "node",
"args": ["/path/to/bear-mcp/dist/index.js"]
}
}
}
```
### Windows
Edit `%APPDATA%\Claude\claude_desktop_config.json`:
```json
{
"mcpServers": {
"bear": {
"command": "node",
"args": ["C:\\path\\to\\bear-mcp\\dist\\index.js"]
}
}
}
```
## Bear Configuration
### Required Settings:
1. **Enable x-callback-url**:
- Open Bear → Settings (⌘,)
- Go to "Advanced" tab
- Enable "Allow x-callback-url"
2. **Generate API Token** (for search and tags):
- Open Bear → Help → Advanced → API Token
- Click "Copy Token"
- In Claude, use: `set_bear_token` with your token
## Usage Examples
### Setup and Testing
```
Check my Bear setup and show me what's available
```
### Reliable Operations (Always Work)
```
Create a new Bear note titled "Project Ideas" with content about machine learning
Add "## Next Steps\n- Review documentation\n- Schedule follow-up" to my "Weekly Review" note
```
### Search Operations (Usually Work)
```
Search my Bear notes for "machine learning" and show me what you find
Get all my Bear tags and help me organize them
```
### Content Analysis (When Search Works)
```
Search for "meeting notes" then help me identify common action items across all results
Find notes tagged with "work" and summarize the main topics
```
## Troubleshooting
### "Search failed: Callback timeout"
- **Normal**: Happens ~10-20% of the time
- **Solution**: Wait 5-10 seconds and retry the same search
- **Tip**: Try simpler search terms (single words work better)
### "No token configured"
Get your token: Bear → Help → Advanced → API Token → Copy Token, then use `set_bear_token`
### "Bear not found"
Make sure Bear is installed and has been opened at least once.
### Browser windows appearing
- **Expected behavior** due to Bear's callback system
- Windows auto-minimize and move off-screen
- Safe to manually close if they persist
- Focus returns to your original window automatically
### No search results
- **Check search term**: Ensure it exists in your notes
- **Verify token**: Use `check_bear_setup` to test
- **Try broader terms**: Single words often work better than phrases
- **Check Bear directly**: Verify the content exists in Bear app
## Technical Details
### HTTP Callback System
The server uses HTTP callbacks (port 51234) to receive data from Bear:
- Bear sends search results and tag data via URL callbacks
- Browser windows appear briefly due to this callback mechanism
- 20-second timeout for Bear responses
- Auto-retry mechanisms for common failures
### Performance Characteristics
- **Fast operations**: Note creation, text addition (~1-2 seconds)
- **Medium operations**: Single note retrieval (~3-5 seconds)
- **Slower operations**: Search, tags list (~5-15 seconds)
- **Timeout threshold**: 20 seconds maximum wait
## Development
To run in development mode:
```bash
npm run dev
```
To test the server:
```bash
npm run build
node dist/index.js
```
## Version History
- **v4.0.2**: Enhanced browser window handling, 20s timeout
- **v4.0.1**: Improved callback reliability, better error messages
- **v4.0.0**: Full functionality restored with callback system
- **v3.1.0**: Documentation-only version (limited functionality)
## Requirements
- Node.js 18 or higher
- Bear app installed on your system
- Claude Desktop application
- macOS (Bear is macOS-only)
## License
MIT