quanticsoul4772/bear-mcp

Bear MCP Server

A Model Context Protocol (MCP) server that provides access to your Bear notes. This server allows AI assistants like Claude to search and read your Bear notes.

Features

Read Operations

• Search notes by title, content, or tags
• Open specific notes by title or ID
• Browse all tags with note counts
• View notes by tag to explore related content
• Direct SQLite queries for fast results

Write Operations

• Create new notes with tags and pin option
• Add text to existing notes (append, prepend, or replace)
• Move notes to trash
• Rename tags across all notes
• Delete tags from all notes

Installation

Option 1: Install from npm (when published)

npm install -g @mcp/bear-server

Option 2: Install from source

# Clone the repository
git clone https://github.com/quanticsoul4772/bear-mcp
cd bear-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Install globally
npm link

Configuration

For Claude Desktop

Add this to your configuration file at ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "bear-mcp": {
      "command": "node",
      "args": [
        "--max-old-space-size=4096",
        "--expose-gc", 
        "--max-semi-space-size=64",
        "/Users/yourusername/Projects/mcp-servers/bear-mcp/dist/index.js"
      ],
      "type": "stdio"
    }
  }
}

Custom Database Path

If your Bear database is in a non-standard location, you can specify it:

{
  "mcpServers": {
    "bear-mcp": {
      "command": "node",
      "args": [
        "--max-old-space-size=4096",
        "--expose-gc",
        "--max-semi-space-size=64",
        "/path/to/bear-mcp/dist/index.js",
        "--db-path",
        "/custom/path/to/database.sqlite"
      ],
      "type": "stdio"
    }
  }
}

Available Tools

open_note

Open a specific note by its title or unique ID.

Example usage:

• "Open my note titled 'Project Ideas'"
• "Show me the note with ID 123ABC-456DEF"

search_notes

Search for notes containing specific terms or tags.

Example usage:

• "Search for notes about machine learning"
• "Find all notes tagged with #work"
• "Search for 'API' in notes with tag #documentation"

get_tags

List all tags in your Bear notes, organized by frequency.

Example usage:

• "What tags do I use in Bear?"
• "Show me all my Bear tags"

open_tag

Display all notes that have a specific tag.

Example usage:

• "Show me all notes tagged #recipes"
• "List notes with the #meeting tag"

get_recent_notes

Get recently modified notes.

Example usage:

• "Show me my 10 most recent notes"
• "What notes did I modify today?"

get_pinned_notes

Get all pinned notes.

Example usage:

• "Show me my pinned notes"
• "What notes have I pinned?"

get_note_stats

Get statistics about your Bear notes.

Example usage:

• "How many notes do I have?"
• "Show me my Bear notes statistics"

get_notes_by_date

Get notes within a specific date range.

Example usage:

• "Show me notes from last week"
• "Find notes created between January 1 and January 31"

create_note

Create a new note in Bear.

Example usage:

• "Create a note titled 'Meeting Notes' with content 'Discussed project timeline'"
• "Create a note with tags 'work, project' and pin it"

add_text

Add text to an existing note (append, prepend, or replace).

Example usage:

• "Append 'Follow-up tasks' to the note with ID 123ABC"
• "Prepend today's date to my meeting notes"
• "Replace the content of note 456DEF with new text"

trash_note

Move a note to trash.

Example usage:

• "Trash the note with ID 789GHI"
• "Delete my note titled 'Old Draft'"

rename_tag

Rename a tag across all notes.

Example usage:

• "Rename tag 'todo' to 'tasks'"
• "Change the #work tag to #office"

delete_tag

Delete a tag from all notes.

Example usage:

• "Delete the tag 'temporary'"
• "Remove the #old-project tag from all notes"

Development

Prerequisites

• Node.js 18 or higher
• Bear app installed on macOS
• TypeScript knowledge for contributions

Building from source

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run in development mode
npm run dev

# Watch for changes
npm run watch

Project Structure

bear-mcp/
├── src/
│   ├── index.ts        # Main server entry point
│   ├── bearDB.ts       # Database connection and queries
│   ├── types.ts        # TypeScript type definitions
│   └── tools/          # Tool implementations
│       ├── index.ts
│       ├── openNote.ts
│       ├── searchNotes.ts
│       ├── getTags.ts
│       └── openTag.ts
├── dist/               # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
└── README.md

Security

This server implements several security measures:

1. Local access only - Runs via stdio, not network accessible
2. Filtered results - Trashed notes are automatically excluded

Troubleshooting

"Bear database not found"

• Ensure Bear is installed and has been opened at least once
• Check if the database exists at ~/Library/Group Containers/9K33E3U3T4.net.shinyfrog.bear/Application Data/database.sqlite
• Use the --db-path option if your database is elsewhere

"Permission denied"

• The server needs read access to the Bear database
• Check file permissions on the database file

No results returned

• Verify that you have notes in Bear
• Check that notes aren't in the trash
• Ensure search terms are spelled correctly

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

License

MIT License - see LICENSE file for details

Acknowledgments

• Inspired by the Bear app team
• Thanks to the MCP community for the protocol and SDKs
• Based on patterns from other MCP server implementations

Disclaimer

This server is not affiliated with or endorsed by Bear (Shiny Frog Ltd.). It's an independent tool that provides access to the Bear database.