# 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)
```bash
npm install -g @mcp/bear-server
```

### Option 2: Install from source
```bash
# 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`:

```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:

```json
{
  "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
```bash
# 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](https://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.