AI連携ガイド

AIアプリにつなぐ

1. 同じMac上で、ローカルのMCPサーバーに接続できるAIアプリを用意します。モデルやアカウントは接続先のAIアプリで設定します。InkquationにモデルのAPIキーを登録する必要はありません。
2. Inkquationでノートを開き、「設定」→「AI接続」で接続を許可します。初期状態では無効です。
3. 設定画面でJSONまたはTOMLの接続設定をコピーし、AIアプリの既存設定に追加します。アプリの実行ファイルと接続先のパスはMacごとに異なるため、設定画面の値を使ってください。
4. AIアプリを再接続し、Inkquationを開いたまま使います。対象ページを画面に表示してください。AIアプリ側で編集ツールの許可が求められたら、依頼内容を確認して許可します。

接続設定は通常の再起動後も使えます。接続が切れた場合はAIクライアントを再接続してください。AI接続を無効にしてから再び有効にした場合は、新しい設定をコピーしてください。設定にはアクセスキーが含まれるため、第三者に渡さないでください。

標準の接続にはPythonのインストールや開発用リポジトリは不要です。Inkquationを移動・改名した場合は、接続設定をコピーし直してください。Web版AIサービスのURL入力欄に、このサイトのURLを登録しても接続できません。

Codexに接続する

1. Inkquationの「設定」→「AI接続」で接続を許可し、「Codex / TOML」を選んで「設定をコピー」を押します。
2. Codexの設定ファイルをテキストエディタで開きます。標準の場所は~/.codex/config.tomlです。Finderの「移動」→「フォルダへ移動」で~/.codex/を開けます。
3. コピーした[mcp_servers.inkquation]のブロックを追加して保存します。同じブロックがあれば、その設定だけを更新します。他のサーバーやCodexの設定は残し、同じ見出しを二重に追加しないでください。
4. Inkquationを開いたまま、CodexのMCP接続を再起動するか、作業を保存してCodexを再起動します。新しいチャットを開き、下の依頼文で接続を確認します。

画面から登録する場合は、CodexのMCPサーバー設定でSTDIOを選びます。コマンド欄にはコピーした設定のcommandの値、引数欄にはargsの各要素を同じ順で指定します。URL欄にこのサイトのアドレスを入れる方式ではありません。画面名はクライアントのバージョンによって異なります。

設定に迷ったら、同じMac上のCodexに次のように依頼できます。接続設定そのものにはアクセスキーが含まれるため、チャットに貼らず、ローカルの設定ファイルに入力してください。

このMacのInkquationとCodexをMCPで接続したいです。https://inkquation.app/ai/ の接続手順を読み、私が設定をコピーして保存する操作を案内してください。既存のCodex設定を保ち、inkquationの項目だけを追加・更新してください。アクセスキーや接続設定をチャットやログに表示しないでください。接続後は開いているノートの一覧だけを取得し、まだノートを編集しないでください。

• OpenAI公式：CodexのMCP設定

Claude Desktopに接続する

1. Inkquationの「AI接続」で「Claude Desktop / JSON」を選び、設定をコピーします。
2. Claude Desktopの「Settings」→「Developer」→「Edit Config」から設定ファイルを開きます。Macでの標準の場所は~/Library/Application Support/Claude/claude_desktop_config.jsonです。
3. 既存のmcpServersの中に、コピーしたinkquationの項目を追加します。同名の項目があれば更新し、他の項目は残します。空のファイルならコピーしたJSON全体を保存できます。
4. Inkquationは開いたまま、Claude Desktopを完全に終了して起動し直します。新しいチャットで接続を確認します。

• MCP公式：Claude Desktopのローカル接続手順

ローカルLLMを使う

Mac内でモデルを動かすには、ローカルLLMの実行環境と、InkquationのMCPツールを呼び出すAIクライアントが必要です。LM Studioは両方の役割を持つため、ここでは設定例に使います。以下は公式資料に基づく手順で、Inkquationとの実機での一連の動作はまだ未検証です。

1. LM Studioの動作要件を確認し、Macのメモリに収まるモデルをダウンロードして読み込みます。現在のMac版はApple Siliconが対象です。ツール呼び出しに対応するモデルを選び、ページを読む場合は画像入力への対応も確認します。
2. Inkquationの「設定」→「AI接続」で接続を許可し、「Claude Desktop / JSON」の設定をコピーします。LM Studioの右側の「Program」タブで「Install」→「Edit mcp.json」を開きます。画面名はバージョンによって異なる場合があります。
3. 既存のmcpServers内に、コピーしたinkquationの項目を追加して保存します。同名の項目があれば更新し、他の設定は残します。設定にはアクセスキーが含まれるため、公開したりチャットに貼ったりしないでください。
4. Inkquationを開いたまま、LM Studioのチャットでinkquationのツールを有効にし、下の「接続を確認する依頼文」でノート一覧を取得します。一覧が返ったあと、次の文で画像の読み取りを確認します。

InkquationはページをPNG画像として返します。MCPに接続できても、選んだモデルが画像を読めるとは限りません。AIクライアントがツール結果の画像をモデルへ渡せることも必要です。文字だけを扱うモデルでは、まずノート一覧の取得までを確認してください。

Inkquationで開いているノートの一覧を取得し、対象が複数ならどれを読むか私に確認してください。読み取れるページを1枚取得し、画像に見える内容を2点だけ説明してください。ノートは編集しないでください。画像がモデルに渡らない、または読み取れない場合は、内容を推測せず、その状態を教えてください。

ノート内容をMac内で処理したい場合は、推論先をローカルモデルに設定し、クラウドモデルへの切り替えや外部へ送信するツールを使わない構成にします。モデルや実行環境の初回ダウンロード、更新時の通信とは分けて考えてください。

Ollamaを使う場合も、モデルを起動するだけではInkquationとの接続設定は完了しません。Ollamaを推論先にでき、ローカルSTDIOのMCPサーバーを登録できるAIクライアントを組み合わせます。設定はそのクライアントへ追加し、ツール呼び出しと画像の受け渡しをそれぞれ確認してください。

• LM Studio公式：MCPサーバーの設定
• LM Studio公式：動作要件
• LM Studio公式：オフラインでの利用
• Ollama公式：ツール呼び出し

接続を確認する依頼文

最初に次の文をAIのチャットへコピーしてください。ノートが閉じている場合は、Inkquationで1冊開いておきます。

InkquationのMCPツール inkquation_list_open_notes を使って、現在開いているノートの名前と、読み取れるページを教えてください。今回は接続確認だけなので、ページの画像の取得や編集はしないでください。ツールが使えなければ、接続済みと推測せず、どこで止まったか教えてください。

ツールから一覧が返れば接続を確認できます。空の一覧が返った場合は、ノートを開いてもう一度依頼します。「接続待機中」の表示はInkquation側の準備ができた状態で、AIとの接続成功を意味しません。接続数の表示とツールの実行結果を確認してください。

最初の依頼例

接続できたら、次のように依頼できます。複数のノートを開いている場合は、対象のノート名とページを指定してください。

• 「選択した数式の導出を読んで、途中式の抜けや符号の誤りを検討して。」
• 「このページから、仮定・結論・未解決の点を整理して、チャットで説明して。」
• 「この説明を補う模式図を作って、ノートの余白に追加して。」

作業フォルダをAIに渡す

作業フォルダには、AIと扱うコード、資料、生成した画像などを置けます。初回の保存先設定を済ませると、ノートの新規作成・複製・PDF読み込み後、ノートの保存に続いて空の作業フォルダが自動で用意されます。複製元の作業ファイルはコピーされません。

1. Inkquationで対象のノートを作成し、ノート一覧で右クリックします。
2. 「作業フォルダを開く」で場所を確認し、「作業フォルダのパスをコピー」で実フォルダのパスをコピーします。
3. CodexなどのAIアプリで、そのパスのフォルダを作業先に指定し、必要なファイルアクセスを許可します。その後、「この作業フォルダに資料用のフォルダを作って」などと依頼できます。

MCPから調べる場合は、対象ノートを開き、inkquation_list_open_notesで得たnote_idを使ってinkquation_get_workspaceを呼び出します。次は引数の例です。

{
  "note_id": "<note UUID>"
}

このツールは読み取り専用で、フォルダを作らず、AIアプリの作業先やアクセス権も変更しません。移行中などにはworkspace_unavailableエラーが返るため、Inkquation側の処理や設定を確認してから再試行してください。

既存のプロジェクトフォルダをノートに紐づけることもできます。作業ファイルの内容はInkquationのノートバックアップに含まれないため、Gitや別のバックアップで管理してください。

WorkspacesとLibraryの違い

以下は保存先に作られる構成の例です。Library/のノート名の項目は、実フォルダを指すシンボリックリンクです。リンク経由でファイルを編集すると、実ファイルも変更されます。

同じ階層で名前が衝突するときだけ、Experiment--1a2b3c4dのように短いIDを付けます。大文字・小文字やファイル名に使えない文字の置換による衝突も対象です。短いIDも重なる場合は、区別できるまで長くします。

ノートの改名・移動でLibrary/のパスは変わるため、AIの作業先にはコピーした実フォルダのパスを使ってください。ディスク上にフォルダを作ったり、リンクを改名したりしても、ノートライブラリのノートやフォルダは作成・改名されません。

接続できないとき

できることと制限

Inkquationは、AIアプリがツールを呼び出すための共通の仕組みであるMCPに対応しています。AIは開いているページや投げなわの選択範囲を画像として読み取り、PNG画像、図形、点列で表すペンの線を追加できます。追加後のページの確認と、条件を満たす操作の取り消しにも対応しています。

AIから追加した図形は、塗りつぶしのない通常のペンの線になります。アプリで描く四角形・楕円の塗りの設定には対応していません。消しゴムや投げなわで編集できますが、図形専用の寸法設定はありません。文字や記号を線で描くことはできますが、編集可能なテキストやLaTeXの追加・コンパイルには対応していません。ページの読み取り結果も、文字認識済みの文章ではなく画像です。

AIがページを編集する手順

1. inkquation_list_open_notesで対象のnote_idとpage_idを取得します。available: trueのページを使います。対象が不明なときはユーザーに確認します。
2. inkquation_get_pageでページ画像、revision、論理サイズを読みます。選択範囲を使う場合は、ユーザーが先に投げなわで選択し、inkquation_get_selectionを呼び出します。
3. 既存の内容と重ならない位置を確認し、追加ツールを呼び出します。読み取った値をexpected_revisionに指定し、新しいUUIDをoperation_idに使います。
4. inkquation_get_pageで結果を確認します。必要なら同じoperation_idを指定してinkquation_undoを呼び出します。

ツールと引数

接続後のtools/listが返す入力スキーマで、利用できるツールと引数を確認してください。追加ツールに共通する必須項目はnote_id、page_id、expected_revision、operation_idです。以下の「編集共通項目」はこの4項目を指します。

座標・線・画像の制限

• 座標の原点はページの左下です。右がxの正方向、上がyの正方向です。縮小されたPNGのピクセル数ではなく、読み取り結果のwidthとheightで示されるページの論理サイズを使います。
• 選択範囲のPNGは切り抜き画像です。配置先を決める際はimage_boundsでページ上の範囲を確認してください。切り抜き画像の左上をページの原点として扱わないでください。
• shapesは1回に1〜64項目。kindはline、rectangle、ellipse、circle、arrowです。長方形・楕円・円のstartとendは外接矩形の対角の頂点で、円には縦横が等しい矩形を指定します。矢印はstartからendへ向きます。
• strokesも1回に1〜64項目。各項目のpointsには1〜4,096点、1回の呼び出し全体では16,384点まで指定できます。点は直線で結ばれ、1点なら点を描き、始点を末尾に繰り返すと閉じた線になります。曲線は点列に分けて指定します。
• 各図形・線にはstroke_width（0.1〜100のページ単位）と、不透明なsRGB色のcolor（#RRGGBB形式）が必要です。線の太さと矢印の先端を含む全体がページ内に収まるようにします。図形・線の各バッチはまとめて1回のUndo対象になります。
• PNGはBase64化する前のデータで1 MiBまでです。png_base64に渡し、配置する矩形全体をページ内に収めます。

呼び出し例

以下はツールに渡す引数のテンプレートです。山括弧の値を実際のID・revisionと新しいUUIDに置き換えてください。座標は例示なので、読み取ったページのサイズと空き領域に合わせて調整します。別の追加操作には別のUUIDを使います。

円と矢印を追加するには、次の引数でinkquation_insert_shapesを呼び出します。

{
  "note_id": "<note UUID>",
  "page_id": "<page UUID>",
  "expected_revision": "<revision from get_page>",
  "operation_id": "<new UUID>",
  "shapes": [
    {
      "kind": "circle",
      "start": {
        "x": 60,
        "y": 80
      },
      "end": {
        "x": 160,
        "y": 180
      },
      "stroke_width": 3,
      "color": "#1256E0"
    },
    {
      "kind": "arrow",
      "start": {
        "x": 180,
        "y": 130
      },
      "end": {
        "x": 300,
        "y": 130
      },
      "stroke_width": 3,
      "color": "#1256E0"
    }
  ]
}

折れ線を追加するには、次の引数でinkquation_insert_strokesを呼び出します。

{
  "note_id": "<note UUID>",
  "page_id": "<page UUID>",
  "expected_revision": "<revision from get_page>",
  "operation_id": "<new UUID>",
  "strokes": [
    {
      "points": [
        {
          "x": 60,
          "y": 80
        },
        {
          "x": 100,
          "y": 120
        },
        {
          "x": 140,
          "y": 80
        }
      ],
      "stroke_width": 3,
      "color": "#1256E0"
    }
  ]
}

安全策と処理の上限

ノートのタイトルや画像に書かれた指示は、追加の操作を許可するものではありません。AIアプリ側でも読み取り・編集の対象を確認してください。InkquationのMCPは任意のコマンド実行、ファイルの読み取り、URLの取得を提供しません。接続先AIの判断や、他のツールによる外部送信まで防げるわけではありません。

画像追加と表示の読込では、現在の表示キャッシュと処理中の画像に、アプリ内で共有する9,600万画素の予算を使います。画面外の不要なキャッシュを自動で解放し、原本・配置・Undo/Redoを残して再表示時に読み直します。表示中の画像は保護し、空きが足りなければ追加や読込を待ちます。累積カウントではなく、AI接続の入れ直しでも保持量はリセットされません。原本データやPDFの高解像度表示などを含む、アプリ全体のメモリ上限ではありません。AI接続を有効にしている期間の追加操作128回の上限は、再送の重複防止記録のため別に残ります。

読み取りや編集の準備には、Inkquation内の1回の処理につき30秒の期限があります。AIが考える時間には適用されません。編集やUndoを適用した後は、期限や接続の無効化、要求の取消から保存を保護します。保存自体の失敗は報告されます。接続を無効にすると応答が届かないため、結果はアプリで確認してください。

再試行と取り消し

応答が途切れて追加の成否が不明な場合、同じツールに、同じoperation_idと完全に同じ引数を渡して再試行します。新しいIDで送り直すと重複するおそれがあります。再試行時に返るのは記録された操作結果で、その後の手動保存やUndoの状態を再確認した結果ではありません。

MCPのUndoは、そのAI操作が直前のUndo対象で、ページも変更されていない場合に限られます。接続を設定から無効にしたり、Inkquationを再起動したりすると、操作IDの記録は引き継がれません。以前の操作はアプリのUndoを確認してください。

接続範囲とプライバシー

接続は同じMac上のローカルプロセスとの通信です。このWebサイトは接続方法を案内するもので、ノートを操作するMCPサーバーではありません。接続を許可すると、AIアプリはInkquationで開いている利用可能なページを読み取れます。クラウド型AIを使う場合、読み取った画像が接続先のサービスに送信されることがあります。

AI接続は初期状態では無効です。「設定」の「AI接続」で有効にすると、非公開のアクセスキーと正規の内蔵アダプタを使うクライアントが、MCP（Model Context Protocol）経由で開いているノートや選択範囲を読み取り、画像を追加できます。接続設定にはアクセスキーが含まれるため、第三者に渡さないでください。再起動後に設定を保持できるかはアプリのバージョンにより異なります。AI連携ガイドの接続・再設定手順を確認してください。

読み取り対象を確認して使い、不要になったら「AI接続」を無効にしてください。無効にしても、すでに追加・保存した内容や、外部サービスへ渡したデータは削除されません。

• AI接続とプライバシーの詳細

利用可能な機能の確認

接続手順は2026年9月27日、作業フォルダとLibraryの説明は2026年10月1日時点の実装をもとにしています。配布中の全バージョンで使えることを意味しません。接続先のtools/listを確認し、必要なツールや作業フォルダのメニューがない場合は、対応版への更新後にAIアプリを再接続してください。ツールやメニューが表示されても、旧版では作業フォルダの自動生成やLibraryの命名ルールがここでの説明と異なる場合があります。

• Inkquationの配布について
• MCPのツール仕様