bear-mcp

bear-mcp

macOS 上の Bear のノートに、AI アシスタント（Claude など）から完全にアクセスできる MCP サーバーです。AI ワークフローから、ノートの検索、読み取り、作成、編集、ロックができます。

なぜ？

Bear には公式 API がありません。このプロジェクトでは、次の 2 つの方法でそのギャップを埋めています。

• 読み取りには Bear の SQLite データベースを直接使用します。高速で、動作が静かで、Bear が終了していても利用できます。
• 書き込みには Bear の x-callback-url スキームを使用します。操作ごとに Bear が一時的に開きますが、確実かつ非破壊的です。
• ロック／ロック解除には AppleScript UI オートメーションを使用します。Bear の URL スキームではこの機能が公開されていないため、これが唯一の方法です。

何ができますか？

ツール	機能
bear_search	テキストやタグでノートを検索します
bear_get	ノートの全内容を読み取ります
bear_recent	最近変更されたノートを一覧表示します
bear_tags	すべてのタグを一覧表示します
bear_create	新しいノートを作成します
bear_prepend	ノートの先頭にテキストを追加します
bear_append	ノートの末尾にテキストを追加します
bear_replace	ノートの本文全体を置き換えます
bear_trash	ノートをゴミ箱に移動します
bear_lock	読み取り専用を切り替えます（ロック／ロック解除）

ノートはタイトルではなく、UUID（またはその先頭 8 文字）で識別されます。

セットアップ

1. インストール

git clone https://github.com/zmainen/bear-mcp.git
cd bear-mcp
pip install -e .

2. MCP 設定に追加

プロジェクトの .mcp.json（または同等のファイル）に追加します。

{
  "bear-notes": {
    "command": "python",
    "args": ["/path/to/bear-mcp/mcp_server.py"]
  }
}

3. アクセシビリティ権限を付与（ロック機能のみ）

bear_lock は AppleScript を使用して Bear のメニュー項目をクリックします。初回の使用時に、macOS からアクセシビリティへのアクセス許可を求められます。これは システム設定 > プライバシーとセキュリティ > アクセシビリティ で一度だけ設定します。

ユースケース

AI 支援によるノート作成。 AI アシスタントにアイデア、会議メモ、調査内容を適切なタグ付きで Bear に直接記録させます。

タグ付けの自動化。 Bear の add-tags URL アクションは動作しません。このサーバーでは、ノート本文にインラインで #tags を書き込むことで回避します。Bear はこれを自動的に認識します。#project/docs のような階層タグも使用できます。

検索と要約。 AI にノート全体から情報を検索して統合するよう依頼できます。テキストで検索し、タグで絞り込み、全内容を読み取れます。

作業完了後のロック。 bear_lock を使ってレビュー後のノートを読み取り専用にし、誤編集を防ぎます。

ライブラリの使用

基盤となる Python ライブラリは MCP なしでも使用できます。

from bear_app import BearNotesAPI

bear = BearNotesAPI()  # auto-detects Bear's database

notes = bear.search_notes("query", tag="project")
note = bear.get_note(note_id="83779062-...")
print(note.title, note.is_locked, note.locked_date)

bear.create_note(title="New note", text="body", tags=["project"])
bear.toggle_read_only(note_id=uuid)

注意点

• ID は UUID であり、行番号ではありません。Bear の内部では ZUNIQUEIDENTIFIER が使われています。
• Bear の URL スキームでは add-tags は動作しません。代わりにインラインの #tag テキストを使用してください。
• スペースには + ではなく %20 を使用してください。 Bear は + を文字どおりに解釈します。このライブラリでは自動的に処理されます。
• ロックには Bear の起動とアクセシビリティ権限が必要です。 内部では UI オートメーションを使用します。確実に動作しますが、目に見えない形ではありません。
• SQLite データベースには書き込まないでください。 すべての書き込みは Bear の URL スキーム経由で行います。

ライセンス

MIT — Zach Mainen、2025