Bear MCP

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

🚀 Quick Start

This Bear MCP Server enables seamless integration between the Bear Note Taking App and Claude Desktop, allowing Claude to directly interact with your Bear notes.

✨ Features (v4.0.2)

Full data retrieval capabilities:

• 🔍 Search notes: Retrieve complete results with metadata.
• 🏷️ Retrieve all tags: Get all tags from your Bear database.
• 📖 Read note content: Analyze and summarize note content.
• ✏️ Create notes: Create new notes and receive their IDs.
• 📝 Add text: Append text to existing notes.
• ✅ Test setup: Conduct comprehensive status checks.

⚠️ 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.
• They usually auto-close within 1-2 seconds.
• It's safe to manually close them if they persist.
• The focus will be automatically returned to your original window.

Search Reliability

Success Rate: Approximately 80 - 90% of searches are reliable.

• Occasional timeouts may occur (20-second limit).
• Simple terms yield better results than complex queries.
• Retry once if a search times out.
• Single words are generally 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: Manually close them if they don't auto-close.
• No results: Try simpler or broader search terms.
• Setup issues: Use check_bear_setup to diagnose.

📦 Available Tools

📦 Installation

1. Clone the repository:

git clone https://github.com/philgetzen/bear-mcp.git
cd bear-mcp

2. Install dependencies:

npm install

3. Build the project:

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:

{
  "mcpServers": {
    "bear": {
      "command": "node",
      "args": ["/path/to/bear-mcp/dist/index.js"]
    }
  }
}

Windows

Edit %APPDATA%\Claude\claude_desktop_config.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 the "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: Occurs about 10 - 20% of the time.
• Solution: Wait 5 - 10 seconds and retry the same search.
• Tip: Try simpler search terms (single words are better).

"No token configured"

Get your token: Bear → Help → Advanced → API Token → Copy Token, then use set_bear_token.

"Bear not found"

Ensure 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.
• Manually close them if they persist.
• The focus will return 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 are often more effective than phrases.
• Check Bear directly: Confirm the content exists in the 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.
• There is a 20-second timeout for Bear responses.
• Auto-retry mechanisms are in place 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: Maximum wait of 20 seconds.

🛠️ Development

To run in development mode:

npm run dev

To test the server:

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