Tinderbox MCP Server

Tinderbox MCP Server

Claude などの AI アシスタントが、macOS 向けの強力なナレッジ管理アプリケーションである Tinderbox と連携できるようにする、Model Context Protocol（MCP）サーバーです。自然言語で Tinderbox を操作したり、アシスタントがアクセスできるほかのサービスと接続したりできます。バックグラウンドでは、Tinderbox の AppleScript 統合を使用して、ノートの作成や更新、ドキュメント内の階層の移動を行います。

🔄 移行のお知らせ：バージョン 0.2.0

バージョン 0.2.0 以降は、リモートアクセス向けの HTTP トランスポートを使用する Python 製に書き換えられました。

Python を採用した理由

Python への書き換えにより、HTTP ベースのリモートアクセスが可能になり、次のことができるようになります。

• コネクターを使用して Claude のモバイルアプリから接続する
• Tailscale または Ngrok を介して、どこからでも Tinderbox サーバーにアクセスする
• Tinderbox サーバーをチームメンバーと安全に共有する
• 安全なアクセスのために、最新の OAuth 認証（GitHub）を使用する

既存のユーザー向け

• TypeScript バージョン 0.1.x は typescript ブランチで引き続き利用できます
• ツールの機能に互換性を損なう変更はありません — すべてのツールはこれまでと同じように動作します
• AppleScript ファイルは同じです — .scpt ファイルに変更はありません
• 移行ガイドについては UPGRADE.md を参照してください

---

含まれる Tinderbox の操作

サーバーには、次の Tinderbox 操作用のツールが含まれています。

• create_note - ドキュメントに新しいノートを作成します
• link_notes - 既存のノート間にリンクを作成します。必要に応じてリンクタイプを指定できます
• update_attributes - 指定したノートの属性値を変更します
• read_note - ノートの内容を取得します（現在はノートのタイトルとテキストのみ）
• get_siblings - 同じ階層レベルにあるノートを検索します（このツールと以降のツールは、ノートのパスと ChildCount を返すため、アシスタントはさらに探索できる場所を把握できます）
• get_children - 指定した親ノートの子ノートをすべて取得します
• get_links - ノートから出ているリンクをすべて検索します

これらの操作を行うには、どのドキュメントを使用するかをモデルが把握している必要があります。既定のドキュメントを設定できます（以下の「設定」セクションを参照）。

前提条件

• Tinderbox
• macOS（Tinderbox の AppleScript 統合に必要）
• Python 3.10 以降
• GitHub アカウント（OAuth 認証に必要）
• MCP 対応クライアント（Claude Desktop と Claude Mobile でテスト済み）

インストール

1. このリポジトリをクローンします。

git clone https://github.com/phkus/tinderbox-mcp.git
cd tinderbox-mcp

2. 仮想環境を作成します。

python3 -m venv venv
source venv/bin/activate

3. 依存関係をインストールします。

pip install -r requirements.txt

4. GitHub OAuth App を設定します。

   • https://github.com/settings/developers にアクセスします
   • 「New OAuth App」をクリックします
   • 次の情報を入力します。
     • Application name：Tinderbox MCP
     • Homepage URL：http://localhost:8000
     • Authorization callback URL：http://localhost:8000/oauth/callback
   • Client ID と Client Secret を保存します

5. サーバーを設定します（いずれかの方法を選択してください）。

   方法 A：.env ファイルを使用する（ほとんどのユーザーにおすすめ）

   cp .env.example .env
   # Edit .env with your credentials
   

   方法 B：環境変数をエクスポートする（テストに適しています）

   export GITHUB_CLIENT_ID="your_client_id"
   export GITHUB_CLIENT_SECRET="your_client_secret"
   export DEFAULT_DOCUMENT="YourDocument"  # Without .tbx extension
   

   方法 C：起動時にインラインで設定する（一度だけの簡易テスト向け）

   GITHUB_CLIENT_ID="your_id" GITHUB_CLIENT_SECRET="your_secret" DEFAULT_DOCUMENT="YourDocument" python src/server.py
   

設定

必須の設定

• GITHUB_CLIENT_ID：GitHub OAuth アプリのクライアント ID
• GITHUB_CLIENT_SECRET：GitHub OAuth アプリのクライアントシークレット

任意の設定

• DEFAULT_DOCUMENT：Tinderbox ドキュメントの名前（.tbx 拡張子を除く）
  • 例：ファイル名が Research.tbx の場合は、DEFAULT_DOCUMENT=Research に設定します
  • 空欄にすると、リクエストごとにドキュメントを指定できます
• APPLESCRIPT_DIR：AppleScript ファイルへのパス（既定値：./applescripts）
• SERVER_PORT：サーバーのポート（既定値：8000）
• SERVER_HOST：サーバーのホスト（既定値：localhost）

注：環境変数は 3 つの方法で設定できます（上記の「インストール」の手順 5 を参照）。永続的な設定には、.env ファイルを使用するのが最も便利です。

サーバーの実行

ターミナルでサーバーを起動します。

source venv/bin/activate  # If not already activated
python src/server.py

次のような出力が表示されます。

Starting Tinderbox MCP Server on http://localhost:8000
MCP endpoint: http://localhost:8000/mcp
AppleScript directory: /path/to/applescripts
Default document: YourDocument

Add this URL as a Connector in Claude settings:
  http://localhost:8000/mcp

このターミナルウィンドウは開いたままにしてください。リクエストを処理するには、サーバーを起動したままにする必要があります。

Claude での使用

Claude Desktop

1. Claude Desktop の設定を開きます
2. 「コネクター」セクションに移動します
3. 「コネクターを追加」をクリックします
4. URL を入力します：http://localhost:8000/mcp
5. 求められたら GitHub で認証します
6. Tinderbox のツールを利用できるようになります

Claude Mobile

1. Claude アプリの設定を開きます
2. 「コネクター」に移動します
3. URL http://localhost:8000/mcp を指定して、新しいコネクターを追加します
4. ブラウザーで GitHub OAuth を完了します
5. 会話で Tinderbox のツールを使い始めます

リモートアクセス（上級者向け）

Tinderbox サーバーにどこからでもアクセスするには（localhost からだけでなく）、次の手順に従います。

オプション 1：Tailscale（セキュリティ面で推奨）

• Mac とモバイルデバイスに Tailscale をインストールします
• 2 台のデバイスがプライベートネットワークを共有します
• コネクター URL の localhost を Tailscale の IP アドレスに置き換えます
• 例：http://100.x.x.x:8000/mcp

オプション 2：Ngrok（一時的なパブリックアクセス）

• Ngrok をインストールします
• 次を実行します：ngrok http 8000
• Claude のコネクターで ngrok の URL を使用します
• 例：https://abc123.ngrok.io/mcp
• 注：無料の ngrok URL は再起動すると変わります

セキュリティに関する注意：リモートアクセスには必ず OAuth 認証を使用してください。サーバーを localhost の外部に公開する際は、認証を無効にしないでください。

使用例

設定が完了したら、Tinderbox のドキュメントを操作するよう Claude に依頼できます。

• 「Tinderbox ドキュメント『Research project』に、会話の主なポイントに基づいてノートを作成してください。」
• 「Tinderbox ドキュメント『Research project』で、ノート『path/to/note』の子ノートを調べ、つながりを提案してください。リンクを作成する前に、私に確認してください。」
• 「Tinderbox ドキュメント『Research project』に、アップロードした画像を再現する図を作成してください。Tinderbox マップ上のノートの位置は、『Xpos』属性と『Ypos』属性で設定できます。X は左から右、Y は上から下に進みます。どちらも負の数を指定でき、マップに実際の境界はありませんが、目安として左上の座標を 0、0、右下の座標をおよそ 40、40 と考えてください。『Color』属性を 16 進コードで変更すると、ノートに色を付けられます。」

警告

update_attribute ツールを使うと、アシスタントは既存のノートの属性（Name 属性や Text 属性を含む）を上書きできます。モデルに提供されるツールの説明では慎重に扱うよう指示していますが、それでもコンテンツが失われる可能性があります。Tinderbox ドキュメントのバックアップを保管してください。

既存のノートの内容を変更できるツールはこれだけです。create_note は、同じコンテナー内に同じ名前の新しいノートを作成するだけだからです。セキュリティをさらに強化するには、設定内のエントリーまたはスクリプトファイルを削除して、update_attribute ツールを取り除くことができます。あるいは、AppleScript を変更して、値のない属性のみを編集できるようにすることもできます。

サーバーの拡張

applescripts フォルダー内の既存のスクリプトファイルは、サーバーの実行中でもいつでも編集できます。カスタムの Tinderbox 操作を追加するには、サーバーを再起動する必要があります。

1. ほかのファイルと同じ場所に、新しい AppleScript（.scpt）ファイルを作成します
2. src/server.py に @mcp.tool() デコレーターを使ってツール定義を追加します
3. サーバーを再起動します

詳しい開発手順については、CLAUDE.md を参照してください。

ロードマップ

• HTTP トランスポートを使用する Python への移行
• GitHub OAuth 認証の追加
• 現在メインコードに含まれているツール設定を、別ファイルに移動
• 「書き出す」→「アウトラインとして」と同様に、ドキュメントの一部または全体の概要をアシスタントに提供するツール
• DEVONthink 用の同様のサーバーを追加
• Bookends 用の同様のサーバーを追加

トラブルシューティング

サーバーが起動しない

「GitHub OAuth credentials required」

• GitHub OAuth アプリを作成したことを確認してください
• GITHUB_CLIENT_ID と GITHUB_CLIENT_SECRET の環境変数を設定してください
• .env ファイルに正しい値が設定されていることを確認してください

「AppleScript directory does not exist」

• プロジェクトのルートに applescripts/ フォルダーがあることを確認してください
• スクリプトを移動した場合は、APPLESCRIPT_DIR 環境変数を確認してください

ツールが動作しない

「Document not found」

• Tinderbox で Tinderbox ドキュメントを開いていることを確認してください
• DEFAULT_DOCUMENT がドキュメント名と完全に一致していることを確認してください（.tbx を除く）
• ドキュメント名では大文字と小文字が区別されます

「Script not found」

• applescripts/ ディレクトリにすべての .scpt ファイルがあることを確認してください
• ファイルの読み取り権限があることを確認してください

接続の問題

Claude から接続できない

• サーバーが実行中であることを確認してください（ターミナルウィンドウを確認してください）
• ブラウザーで URL をテストしてください：http://localhost:8000/mcp
• ファイアウォールがポート 8000 をブロックしていないことを確認してください
• リモートアクセスの場合は、Tailscale/Ngrok が正しく設定されていることを確認してください

謝辞

このプロジェクトは、Josh Rutkowski 氏の applescript-mcp サーバーに着想を得ています。2 つのサーバーの主な違いは、applescript-mcp が AppleScript の全内容をターミナルに渡すのに対し、この実装では個別のスクリプトファイルを呼び出す点です。これにより、パラメーター内の引用符などの特殊文字に関する問題が解決されました。

アプリをスクリプトで操作できるようにしてくださった、Tinderbox の開発者である Mark Bernstein 氏に感謝します。

ライセンス

MIT

貢献

こちらで貢献していただくか、Tinderbox フォーラム（ユーザー名：pkus）でフィードバックをお寄せください。

これは基本的に AppleScript を実行するサーバーです。そのため、MacOS 上でスクリプト操作できるものなら、ほかの用途にも適応できます。

---

注：TypeScript 版のドキュメントについては、typescript branch を参照してください。