Bear Notes MCP server

The Bear Notes MCP Server connects your personal Bear Notes knowledge base to AI assistants using semantic search and RAG (Retrieval-Augmented Generation). This allows AI assistants to understand the meaning of your notes, not just perform simple text matching, creating more intelligent interactions with your personal knowledge base.

Installation

Basic Setup

1. Clone the repository and install dependencies:

git clone [your-repo-url]
cd bear-mcp-server
npm install

2. Make the scripts executable:

chmod +x src/bear-mcp-server.js
chmod +x src/create-index.js

Creating the Index

Before using the server, create vector embeddings of your notes:

npm run index

This process may take several minutes depending on how many notes you have, as it converts all notes into mathematical vectors that capture their meaning.

Configuration

Update your MCP configuration file with the following settings:

{
  "mcpServers": {
    "bear-notes": {
      "command": "node",
      "args": [
        "/absolute/path/to/bear-mcp-server/src/bear-mcp-server.js"
      ],
      "env": {
        "BEAR_DATABASE_PATH": "/Users/yourusername/Library/Group Containers/9K33E3U3T4.net.shinyfrog.net.bear/Application Data/database.sqlite"
      }
    }
  }
}

Make sure to replace the paths with your actual installation locations.

Features

• Semantic Search: Finds notes based on meaning rather than just keywords
• RAG Support: AI assistants can pull in relevant context from your notes
• Local Processing: All processing runs on your machine with no data leaving your computer
• Graceful Fallbacks: Falls back to traditional search if semantic search is unavailable

How It Works

Technical Implementation

This server uses the Xenova implementation of transformers.js with the all-MiniLM-L6-v2 model to:

• Create 384-dimensional vectors capturing the semantic essence of your notes
• Process everything locally on your machine
• The first startup might be slow while the model loads, but performance improves after that

Process Flow

1. Your query is converted into a vector using the transformer model
2. This vector is compared to pre-indexed vectors of your notes
3. Notes with similar meanings are returned, regardless of exact keyword matches
4. AI assistants use these relevant notes as context for their responses

Available Tools for AI Assistants

The server provides these tools for AI assistants:

1. search_notes: Find notes that match a query

   • Parameters: query (required), limit (optional, default: 10), semantic (optional, default: true)

2. get_note: Fetch a specific note by its ID

   • Parameters: id (required)

3. get_tags: List all tags used in your Bear Notes

4. retrieve_for_rag: Get notes semantically similar to a query, formatted for RAG

   • Parameters: query (required), limit (optional, default: 5)

Requirements

• Node.js version 16 or higher
• Bear Notes for macOS
• An MCP-compatible AI assistant client

Troubleshooting

If you encounter issues:

1. Double-check your Bear database path
2. Ensure you've run the indexing process with npm run index
3. Check permissions on the Bear Notes database
4. Verify the server scripts are executable
5. Look for error messages in the logs

Docker Implementation (Optional)

1. Build the Docker image

docker build -t bear-mcp-server .

2. Index your notes

docker run \
  -v /path/to/your/NoteDatabase.sqlite:/app/database.sqlite \
  -e BEAR_DATABASE_PATH=/app/database.sqlite \
  bear-mcp-server \
  npm run index

3. Start the server

docker run \
  -v /path/to/your/NoteDatabase.sqlite:/app/database.sqlite \
  -e BEAR_DATABASE_PATH=/app/database.sqlite \
  -p 8000:8000 \
  bear-mcp-server

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":"node","args":["/absolute/path/to/bear-mcp-server/src/bear-mcp-server.js"],"env":{"BEAR_DATABASE_PATH":"/Users/yourusername/Library/Group Containers/9K33E3U3T4.net.shinyfrog.net.bear/Application Data/database.sqlite"}}'

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": "node",
            "args": [
                "/absolute/path/to/bear-mcp-server/src/bear-mcp-server.js"
            ],
            "env": {
                "BEAR_DATABASE_PATH": "/Users/yourusername/Library/Group Containers/9K33E3U3T4.net.shinyfrog.net.bear/Application Data/database.sqlite"
            }
        }
    }
}

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": "node",
            "args": [
                "/absolute/path/to/bear-mcp-server/src/bear-mcp-server.js"
            ],
            "env": {
                "BEAR_DATABASE_PATH": "/Users/yourusername/Library/Group Containers/9K33E3U3T4.net.shinyfrog.net.bear/Application Data/database.sqlite"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect