Bear Notes MCP server

This MCP server provides Claude with access to your Bear App notes, allowing you to search, retrieve, and analyze your notes directly from Claude Desktop or any MCP-compatible client. It offers powerful search capabilities across your note content with features for code analysis and content management.

Installation

Prerequisites

• macOS (Bear App is macOS/iOS only)
• Bear App installed and with some notes
• Python 3.8 or higher
• Claude Desktop (for desktop integration)

Setup Steps

1. Clone or download the server script

   git clone github.com/netologist/mcp-bear-notes
   

2. Create a virtual environment

   uv install
   source .venv/bin/activate
   

3. Test the server

   uv run python main.py
   

Claude Desktop Integration

Configuration File Location

Edit your Claude Desktop configuration file:

~/Library/Application Support/Claude/claude_desktop_config.json

Add MCP Server Configuration

{
  "mcpServers": {
    "bear-notes": {
      "command": "/full/path/to/mcp-bear-notes/.venv/bin/python",
      "args": ["/full/path/to/mcp-bear-notes/main.py"],
      "env": {
        "PYTHONPATH": "/full/path/to/mcp-bear-notes/.venv/lib/python3.13/site-packages"
      }
    }
  }
}

Important: Replace /full/path/to/ with your actual file paths.

Restart Claude Desktop

Close and reopen Claude Desktop to load the MCP server.

Usage Examples

Once integrated with Claude Desktop, you can use natural language to interact with your Bear notes:

Basic Search

"Search my Bear notes for Docker examples"
"Find notes about Python APIs"
"Show me my recent notes from this week"

Technical Content

"Find my Kubernetes deployment manifests"
"Look for JavaScript code examples in my notes"
"Show me notes with YAML configurations"

Specific Retrieval

"Get the note titled 'Development Setup'"
"Find notes tagged with 'work'"
"Show me all my available tags"

Available Tools

search_bear_notes(query, tag, limit)

Search notes by content and tags.

• query: Text to search for
• tag: Filter by specific tag (without #)
• limit: Max results (default: 20)

get_bear_note(note_id)

Retrieve a specific note by its unique ID.

• note_id: Bear note's unique identifier

find_kubernetes_examples(resource_type)

Find Kubernetes-related content.

• resource_type: K8s resource (deployment, service, etc.)

find_code_examples(language, topic, limit)

Search for code examples.

• language: Programming language
• topic: Code topic/domain
• limit: Max results (default: 15)

find_notes_by_title(title_query, exact_match)

Search notes by title.

• title_query: Title text to search
• exact_match: Exact or partial matching

get_recent_notes(days, limit)

Get recently modified notes.

• days: How many days to look back (default: 7)
• limit: Max results (default: 20)

list_bear_tags()

List all tags found in your notes.

Troubleshooting

Common Issues

Server won't start

• Check Python path in configuration
• Verify virtual environment activation
• Ensure fastmcp is installed

No notes found

• Verify Bear database path exists
• Check that Bear App has been opened at least once
• Confirm notes aren't in trash

Claude Desktop integration fails

• Validate JSON syntax in config file
• Check file paths are absolute, not relative
• Restart Claude Desktop after configuration changes

Permission denied errors

• Ensure script has execute permissions: chmod +x main.py
• Check Bear database file permissions

Debug Mode

Run the server directly to see debug output:

python main.py

Log Files

Check Claude Desktop logs for MCP server errors:

~/Library/Logs/Claude/

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "bear-notes" '{"command":"/full/path/to/mcp-bear-notes/.venv/bin/python","args":["/full/path/to/mcp-bear-notes/main.py"],"env":{"PYTHONPATH":"/full/path/to/mcp-bear-notes/.venv/lib/python3.13/site-packages"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "bear-notes": {
            "command": "/full/path/to/mcp-bear-notes/.venv/bin/python",
            "args": [
                "/full/path/to/mcp-bear-notes/main.py"
            ],
            "env": {
                "PYTHONPATH": "/full/path/to/mcp-bear-notes/.venv/lib/python3.13/site-packages"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "bear-notes": {
            "command": "/full/path/to/mcp-bear-notes/.venv/bin/python",
            "args": [
                "/full/path/to/mcp-bear-notes/main.py"
            ],
            "env": {
                "PYTHONPATH": "/full/path/to/mcp-bear-notes/.venv/lib/python3.13/site-packages"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect