mcp-bear

This MCP server provides a local bridge to Bear, the note-taking app. It exposes a set of endpoints that map to Bear actions (such as opening notes, creating notes, adding text or files, managing tags, and performing organizational tasks like archive, trash, and todolist actions). The server runs as an MCP server that you load into your preferred MCP client (e.g., Claude, LM Studio, or Goose-configured environments) via UV. To use it, install UV, install this MCP bundle from the repository, and configure the Bear MCP server with your Bear API token. Once running, you can call endpoints like /open-note, /create, /add-text, /add-file, /tags, /open-tag, /rename-tag, /delete-tag, /trash, /archive, /untagged, /todo, /today, /locked, /search, and /grab-url to interact with Bear from your MCP client. The server is designed to work with Bear’s X-callback-url style actions and exposes a range of Bear operations through MCP-compatible endpoints.

Prerequisites:

• A machine with Python 3.8+ installed
• UV runtime installed (see uv docs: https://docs.astral.sh/uv)
• Git installed (for cloning from Git repositories)

Installation steps:

1. Ensure UV is installed on your system. Follow the UV installation guide in the linked docs.

2. Install the Bear MCP server via UVX (the easiest path uses the Git source):

   uvx --from git+https://github.com/jkawamoto/mcp-bear mcp-bear

   This installs the mcp-bear server as an MCP server called bear (the name is defined by your config, as shown below).

3. Configure environment with your Bear API token when running (or supply it via your environment manager):

   BEAR_API_TOKEN=<your_token>

4. Run the server (as part of your MCP client setup, using the provided mcp_config):

   Use the mcp_config example to run the server in your environment. For Goose-based installations, use the uvx invocation shown in the configuration snippet.

5. Connect to the server from your MCP client (Claude, LM Studio, Goose, etc.). Provide the Bear API token when prompted or via the environment variable BEAR_API_TOKEN.

Note: If you are configuring Claude Desktop or LM Studio manually, you can add the provided Bear MCP server configuration to their respective MCP settings as described in the README.

Tips and considerations:

• BEAR_API_TOKEN must be kept secret. Do not commit it or expose it in public configs.
• The server exposes a range of Bear actions. If an action is not behaving as expected, verify Bear’s API token permissions and ensure Bear is accessible from the client running the MCP server.
• For Goose users, you can configure the mqtt-like extension entry with cmd: uvx and args pointing to the repository as shown in the README.
• If you plan to use Claude Desktop, you can import the mcp-bear bundle from the Releases page or configure the JSON example under mcpServers in Claude's config.
• LM Studio users can add an MCP server via the provided add-deeplink link and name it bear; the config payload is already encoded in the README image link.
• If you need to reconfigure, you can edit the local config files (Goose: ~/.config/goose/config.yaml; Claude: claude_desktop_config.json) to point to the uvx/mcp-bear combo.