Bear App MCP Server

A Model Context Protocol (MCP) server that provides integration with Bear App using its X-callback-URL scheme. This server enables AI assistants to interact with Bear notes, create new content, search, and manage tags.

Features

• Note Management: Create, open, and modify notes with full metadata retrieval

• Text Operations: Add, append, prepend, or replace text in existing notes

• Search: Search through notes and tags with complete result data

• Tag Management: Get, open, rename, and delete tags with real-time data

• Organization: Archive, trash, and organize notes

• Web Content: Grab content from URLs to create notes with returned metadata

• Special Views: Access Today, Todo, and Untagged note collections with full note lists

• Callback Integration: Advanced x-success callback support for comprehensive data retrieval

• Silent Operation: Custom URL scheme prevents unwanted browser windows during callbacks

Related MCP server: Bear MCP Server

Requirements

• macOS (Bear App is macOS only)

• Bear App installed and running

• Node.js 18+

• Bear API token (for some operations)

Quick Installation

chmod +x ./setup.sh && ./setup.sh

Manual Installation

1. Clone and go to the project:

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

2. Install dependencies:

npm install

3. Build the project:

npm run build

4. Build binaries:

/path/to/bear-mcp-server/dist/index.js

Getting Bear API Token

Some operations require a Bear API token:

On macOS:

1. Open Bear App

2. Go to Help → Advanced → API Token → Copy Token

3. The token will be copied to your clipboard

Configuration

Add the server to your MCP client configuration. For Claude Desktop, add to your claude_desktop_config.json:

{
  "mcpServers": {
    "bear": {
      "command": "node",
      "args": ["/path/to/bear-mcp-server/dist/index.js"],
      "env": {
        "BEAR_TOKEN": "your-bear-api-token-here"
      }
    }
  }
}

Available Tools

Core Note Operations

• bear_open_note: Open a note by ID or title (returns full note data and metadata)

• bear_create_note: Create a new note with title, content, and tags (returns note ID and title)

• bear_add_text: Add text to existing notes (append, prepend, replace)

Search & Discovery

• bear_search: Search notes by term and/or tag (returns complete search results with metadata)

• bear_get_tags: Retrieve all available tags (returns full tags array)

• bear_open_tag: Open notes with specific tag(s) (returns notes list with details)

Organization

• bear_trash_note: Move notes to trash

• bear_archive_note: Archive notes

• bear_get_untagged: Get notes without tags (returns complete untagged notes list)

• bear_get_todo: Get notes marked as todos (returns todo notes with metadata)

• bear_get_today: Get today's notes (returns today's notes with details)

Tag Management

• bear_rename_tag: Rename existing tags

• bear_delete_tag: Delete tags

Web Integration

• bear_grab_url: Create notes from web page content (returns created note ID and title)

Security Notes

• The server uses macOS open command to execute Bear URLs

• API tokens should be kept secure and not shared

• Some operations require Bear to be unlocked (not in locked state)

• Encrypted notes cannot be accessed via the API

Development

Run in development mode:

npm run dev

Build for production:

npm run build

Enhanced Callback Integration

This server leverages Bear's x-success callback mechanism to provide comprehensive data retrieval:

• Real-time Data: Most operations return actual Bear data instead of generic success messages

• Complete Results: Search operations return full note arrays with metadata

• Immediate Access: Created notes return their IDs for follow-up operations

• Rich Metadata: Notes include titles, identifiers, tags, dates, and content

• Silent Operation: Auto-closing HTML response minimizes browser window interference

• Instant Close: Multiple JavaScript methods ensure browser windows close immediately

Callback-Enhanced Tools

The following tools use advanced callback integration for enhanced data retrieval:

• bear_open_note, bear_create_note, bear_search, bear_get_tags

• bear_open_tag, bear_get_untagged, bear_get_todo, bear_get_today, bear_grab_url

Technical Implementation

Auto-Close HTTP Response: Uses standard http://localhost:port/callback URLs but returns HTML with multiple browser-closing mechanisms:

• Immediate window.close() JavaScript execution

• Meta refresh redirect to about:blank

• Hidden body styling to prevent content flash

• Cache-control headers to prevent browser caching

Browser Window Minimization: While a browser window may briefly appear, it closes automatically within milliseconds, providing near-silent operation.

Limitations

• macOS only (Bear App limitation)

• Some operations require user interaction with Bear

• Callback operations have 10-second timeout limit (with automatic fallback)

• File attachments require base64 encoding

• Bear must be unlocked for encrypted note access

• Brief browser window flash may occur (auto-closes within milliseconds)

License

MIT License - feel free to modify and distribute

Contributing

Contributions welcome! Please ensure:

• TypeScript compilation passes (npm run build)

• Bear URL schemes are correctly implemented

• Callback integration works properly

• Error handling is comprehensive

• Documentation is updated

• Test with npm run test (requires Bear App for full functionality)

Links

• Bear App

• Bear X-callback-URL Documentation

• Model Context Protocol