ローカルファーストで決定論的なIDA Pro/Home向けMCPサーバー：109の厳格なスキーマによるリバースエンジニアリング操作、証拠に基づく検出結果、ポリシーで制御されたIDB編集。

インストールの前に

必要なもの:

• IDA ProまたはIDA Home 9.2以降で、使用可能なidat/idat64実行ファイルがあること。リポジトリのライブテストエビデンスはIDA 9.3と9.4をカバーしており、9.2が宣言された互換性の下限です。
• ホストとインストーラー用のPython 3.11以降。
• 検査予定のバイナリに対してIDAを実行する権限、および管理されたPython環境、セッションファイル、IDBコピーのための十分なディスク容量。
• ローカルstdioサーバーをサポートするMCPクライアント。例: Claude Code、Codex、OpenCode、Claude Desktop、Cursor、VS Code/Copilot、Windsurf、Cline、Roo Code、Gemini CLI、Antigravity。

通常の解析には言語モデルや埋め込みモデルは不要です。オプションのセマンティック検索機能はデフォルトでローカルモデルを使用し、モデルが構成されていない場合は無効のままです。

デフォルトのランタイムはidatです。セッションごとに1つのヘッドレスIDAプロセスです。idalibバックエンドは実験的であり、idaproパッケージがアクティベートされたIDA 9.3以降のインストールが必要で、初回インストールには不要です。

ソースチェックアウトからのインストール

インストーラーはインストールルートの下に管理された環境を作成し、チェックアウトの固定コピーをそこにインストールし、サポートされているクライアントの場所に対してクライアント設定を書き込みます。リポジトリのルートから実行します:

既知のIDAインストールがある場合は、明示的に渡します:

非対話実行の場合:

インストーラーはIDADIR、IDA_DIR、PATH上のIDA実行ファイル、および一般的なインストールディレクトリを通じてもIDAを見つけることができます。--ida-versionは複数のインストールが存在する場合にバージョンを選択します。まず--dry-runを使用して計画された変更を確認してください。

インストーラーは、あなたが選択または要求しない限り埋め込みモデルをダウンロードしません。組み込みのクライアントマップにあるすべてのクライアントの場所に対して設定ファイルを作成または更新する可能性があり、マシンにインストールされていないクライアントも含まれます。インストールルートのinstall-report.jsonを確認し、必要に応じて未使用のエントリを削除してください。既存の通常の設定ファイルは変更前にバックアップされます。不正な形式、シンボリックリンク、または非通常ファイルは上書きされずに拒否されます。

インストール後はMCPクライアントを再起動して、設定を再読み込みさせてください。

エージェントハーネスはツールサーフェスをライブに検出します。tools/listはすべてのオペレーションをそのスキーマとともに列挙し、ida_help(topic="...")は正確な引数と例を返します。静的なスキルファイルはインストールされません。

デフォルトのインストールルートは:

• LinuxおよびmacOS: ~/.local/share/ida-pro-mcp
• Windows: %LOCALAPPDATA%/ida-pro-mcp

別の場所を選択するにはIDA_PRO_MCP_HOMEを設定するか、--install-rootを渡してください。

リリース成果物からのインストール

アルファリリースはGitHub Actionsによってビルドされ、手動でプレリリースとして公開されます。リリースが利用可能な場合は、リリースページからbundle.zipまたはbundle.tar.gzアセットとそのSHA256SUMSファイルをダウンロードしてください。チェックサムを検証し、バンドルを展開し、そのトップレベルディレクトリからインストーラーを実行します:

リリースには、スクリプトによるPythonインストール用のwheelとソースディストリビューションも含まれています。バンドルは、インストーラーとMCPクライアントを構成するために必要なすべてのプロジェクトファイルを含むため、最も簡単なルートです。リリースはアルファ品質です。アップグレードする前に、元のバイナリとIDBを保持し、リリースノートを読んでください。

MCPクライアントの接続

インストーラーは、認識しているクライアント設定パスに対してサーバーエントリを書き込みます。Gemini CLI、Antigravity、Antigravity IDE、Antigravity CLI、Claude Code、Codex、Copilot CLI、OpenCode、Claude Desktop、Cursor、VS Code、Windsurf、Cline、Roo Codeをサポートしています。 OpenCodeとCopilotファミリーのクライアントは異なる設定形式を使用します。インストーラーにそれらのファイルを書き込ませるか、OpenCodeセットアップガイドに従ってください。

一般的なJSON形式を使用するクライアントの場合、エントリは次と同等です:

Windowsでは、<install-root>/.venv/Scripts/python.exeにある管理されたインタープリターを使用してください。重要な詳細は、管理されたインタープリター、-u -m ida_pro_mcp.host.server、選択されたIDAディレクトリ、およびIDA_MCP_TOOL_SURFACE=agentです。クライアントをinstall.pyに向けないでください。そのファイルはインストーラーであり、MCPサーバーではありません。

クライアント設定を変更した後は、クライアントを完全に再起動し、利用可能なオペレーションにida_helpが表示されることを確認してください。クライアントがレガシーの広範なtool(action=...)インターフェースのみを表示する場合は、環境がIDA_MCP_TOOL_SURFACE=legacyではなくデフォルトのagentサーフェスを選択していることを確認してください。

最初の有用なセッション

まずテストバイナリへの絶対パスを使用してください。バイナリを開くと通常、IDAの初期解析が完了するまで待機します。大きなバイナリは時間がかかることがあります。

正確な引数スキーマが必要な場合はいつでもida_help(topic="ida_decompile")を使用してください。公開オペレーションのスキーマは厳格です。未知の引数は拒否されます。アドレスは個々のオペレーションのコントラクトに従って整数または文字列として受け入れられる場合があります。クライアント内のオペレーションについてida_helpが示す形式を使用してください。

小さな調査記録の場合、ワークスペースfindingsオペレーションは次のとおりです:

ワークスペースfindingsはIDBの編集とは別に保持されます。アクティブなポリシーがワークスペース書き込みを許可している場合、ida_write_findingはfindingをローカルに記録します。そうでない場合、サーバーはポリシーエラーを返します。ida_publish_findings(dry_run=true)はIDBの変更をプレビューします。公開、名前変更、パッチ適用、およびその他のIDB変更はポリシーでゲートされ、オペレーションが承認を公開している場合は、そのオペレーションの文書化された承認が必要です。

オペレーションの概要

フロントページはタスク指向のままですが、このコンパクトなインデックスは公開サーフェスをスキャンしやすくします。以下の各名前は、呼び出される際にida_が接頭辞として付きます。完全なスキーマと例は、tools/listとida_help(topic="...")を通じてライブに利用可能です。

何が安全で、何が安全でないか

サーバーのベースラインポリシーはassistです。セッションはオペレーターのベースラインポリシーを厳格化することはできますが、緩和することはできません。ポリシーは決定論的です。クライアントが要求したからといって、危険なオペレーションが安全であると判断することはありません。

読み取り専用の検査が通常の出発点です。例としては、ida_overview、ida_find、ida_list_functions、ida_list_strings、ida_list_imports、ida_decompile、ida_disassemble、ida_xrefs_to、ida_callers、ida_callees、ida_callgraph、ida_read_bytes、および計算オペレーションがあります。これらは依然としてローカルファイルとIDAリソースを消費し、MCPクライアントはその結果を受け取ります。

以下のアクションは永続的な状態を変更するかコードを実行するため、高インパクトとして扱うべきです:

• ida_rename、ida_comment、ida_patch_bytes、関数/型/セグメント/データの変更、シグネチャの適用、ida_save_idb、スナップショット、およびundo/restoreオペレーションは、IDBまたは関連する状態を変更する可能性があります。
• ida_publish_findingsはfindingsをIDBに書き込みます。まずそのdry-run形式を実行してください。非dry-run形式はゲートされています。
• ida_close_sessionはライブIDAランタイムを破棄し、セッションの観点からは破壊的です。
• ida_pythonはアクティブなIDAプロセスで任意のPythonを実行します。セーフモードではブロックされ、通常のポリシーでは明示的なリスク承認が必要です。
• ida_emulateは制御されたチェックに有用ですが、エミュレーターを変更するアクションには対応する承認が必要です。
• ida_til_exportとida_til_importはファイルシステムにアクセスし、ゲートされています。ファイルシステムパスは、そのガードが適用される場合、構成されたメモリルートによって制約されます。

--disable-policyを便利フラグとして使用しないでください。これはIDA_MCP_POLICY_MODE=offを設定し、書き込み承認やその他のワークフロー制御を含むすべてのポリシーゲートを無効にします。呼び出しが拒否された場合は、そのオペレーションのida_helpエントリを読み、そのオペレーションのスキーマがサポートしている場合にのみ、正確な承認済み引数を指定してください。

IDAがまだ初期解析を実行している間、セーフモードは一部の全バイナリ解析、インデックス作成、およびスクリプトオペレーションをブロックします。これは初期セッションの呼び出しを狭く保つことを意図しています。ガードを迂回するのではなく、ida_session_statusまたはida_session_healthをポーリングしてください。

ブリッジはループバックでリッスンし、セッションごとのトークンを使用します。これはネットワークサービスではありません。ブリッジポートを信頼できないネットワークに公開または転送しないでください。インポートされたスクリプト、トレース、バイナリ、コーパスデータ、およびクライアントリクエストは信頼できない入力として扱ってください。

プライバシーとデータ処理

通常のホストからIDAへのパスはローカルです。プロジェクトは解析パスに組み込みのLLMサービスを実行せず、ローカル埋め込みはオプトインです。ただし、それによってワークフロー全体が自動的にオフラインになるわけではありません:

• 接続されたMCPクライアントは、パス、シンボル、文字列、バイト、逆コンパイル、findings、およびその他の結果を受け取ります。クライアントまたはそのモデルプロバイダーは、独自のアカウント、モデル、および保持設定に従ってそのコンテキストを送信する場合があります。IDA Pro MCPはそれらの転送を制御できません。
• Gemini埋め込みバックエンドを明示的に選択した場合、サーバーは完全な逆コンパイルではなく、コンパクトな行動シグネチャをGoogleに送信します。シグネチャには依然としてコード由来の呼び出し、定数、文字列リテラル、および制御フロー情報が含まれる可能性があります。ワークステーション上に留めておく必要があるバイナリに対しては有効にしないでください。
• インストーラーの依存関係ダウンロード、オプションのモデルおよびllama-serverダウンロード、オプションの脅威コーパスダウンロード、および外部のRizin/radare2統合は、有効にするとネットワークリクエストを行う場合があります。
• ローカルキャッシュ、ログ、セッションメタデータ、管理されたIDB、およびブラックボードには、パス、解析メタデータ、およびfindingsが含まれる場合があります。インストール/データディレクトリを保護してください。Gemini AI Studioキーをインストーラーに渡す場合、キーは生成されたMCPクライアント環境ブロックに書き込まれる可能性があります。環境ベースの資格情報を優先し、クライアント設定を確認してください。

ローカルのみのセットアップには、デフォルトのローカルランタイムを使用し、Geminiおよびその他のオプションのダウンロードを無効のままにし、組織のデータポリシーに従ってMCPクライアントとそのモデルを構成してください。「ローカルのみ」であっても、クライアントが独自のモデルプロバイダーに何を送信するかを確認する必要があります。

よくあるトラブルシューティング

インストーラーがIDAを見つけられない

インストールディレクトリを明示的に渡してください:

IDADIRまたはIDA_DIRを設定することもできます。複数のインストールが見つかった場合は、--ida-version 9.3または--no-ida-promptを使用して選択を制御してください。選択したディレクトリに実行可能なidatまたはidat64が含まれていることを確認してください。

クライアントがIDA Pro MCPを表示しない

クライアントを再起動し、その設定エントリを検査してください。そのコマンドが管理されたvenv Pythonと-u -m ida_pro_mcp.host.serverを使用していること、およびenvブロックに正しいIDADIRが含まれていることを確認してください。install-report.jsonを確認してください。インストーラーはクライアント更新の失敗を記録し、変更されたファイルの隣にバックアップを保持します。OpenCodeとCopilotファミリーの設定形式は、一般的なJSONの例とは異なります。

バイナリを開くのに時間がかかる、またはスタックしたように見える

通常のida_open_binary呼び出しは初期解析を待機します。ida_session_statusとida_session_healthを確認し、大きなバイナリにはより多くの時間を許可し、インストール/データディレクトリの下にあるセッションごとのログを確認してください。バックグラウンドオープンオペレーションも利用可能ですが、その非同期動作とセーフモードの制限を理解している場合を対象としています。

書き込みオペレーションが拒否される

これは通常、構成どおりにポリシーが機能していることを意味します。ida_helpを使用して、オペレーションの正確なスキーマとその承認要件を検査してください。任意の引数を追加しないでください。スキーマは厳格です。ポリシーを変更する前に、IDA_MCP_POLICY_MODEとオペレーターポリシーファイルを確認してください。すべてのポリシーゲートを無効にすることは、別個の、意図的に安全でない選択です。

セマンティック検索が利用できない

セマンティック検索はオプションであり、インデックスと互換性のある埋め込みバックエンドが必要です。通常のリスト、検索、逆コンパイル、およびクロスリファレンス作業には必要ありません。オプションのローカルパスをセットアップするには、インストーラーの明示的なembedderオプションを使用します。例えば:

インストーラーは--embedder-doctorを実行したり、明示的なモデルパスを使用したり、要求された場合に選択されたモデルとllama-serverをダウンロードすることもできます。モデルのライセンス、ディスク使用量、およびネットワークダウンロードはあなたの責任です。モデルが欠落している場合、サーバーはセマンティック検索が実行されたふりをするのではなく、利用不可として報告するはずです。

インストーラーがクライアント設定を拒否する

報告されたJSON、JSONC、またはTOML構文を修正し、インストーラーを再実行してください。また、予期しないターゲットを上書きしないように、シンボリックリンクおよび非通常の設定パスを拒否します。既存の通常ファイルはバックアップされます。インストーラーのデフォルトのロールバック動作は、後のフェーズが失敗した場合にそれらのバックアップを復元できます。

IDAセッションまたはランタイムが失敗する

ida_session_health、セッションログ、およびブリッジログを確認してください。クライアントがインストーラーが記録したものと同じインストールルートとIDADIRを使用していることを確認してください。デフォルトのidatバックエンドは各セッションに独自のプロセスを与えます。基本的なインストールを診断している間は、実験的なidalibに切り替えないでください。

参考資料

• プロジェクトwiki — タスク指向のインストール、調査、編集、およびトラブルシューティングガイド。
• ローカルwikiページ — 組み込みwikiツール用に出荷された同じ手書き資料。
• ライブオペレーション検出 — tools/listとida_helpがすべての公開オペレーション、スキーマ、および例を公開します。
• 安全モデル — 信頼境界、ポリシーモード、ループバックトランスポート、セッション所有権、およびファイルシステムガード。
• 調査ワークスペース — findings、エビデンス、ターゲット、およびエクスポート。
• インテリジェンスと埋め込み — ローカルおよびオプションのGemini検索バックエンド。
• OpenCodeセットアップ — OpenCode設定。
• アーキテクチャ — 実装の詳細を必要とする読者向けのホスト、IDAランタイム、およびデータフロー。
• セキュリティポリシー — 報告とセキュリティガイダンス。
• ライブIDAテスト — リポジトリのテストが実際のIDAインストールについて何を証明し、何を証明しないか。
• バージョニングとリリースチェックリストおよび変更履歴 — アルファステータスとリリース履歴。
• ドキュメントインデックス — 維持されているガイド、リファレンス、wikiページ、および研究ノートの完全なマップ。

正確なオペレーション名については、生成されたリファレンスを使用するか、実行中のサーバーにida_helpで問い合わせてください。古いtool(action=...)バックエンドは互換性のために引き続き利用可能で、IDA_MCP_TOOL_SURFACE=legacyで選択されます。新しい統合では、厳密なスキーマのida_*サーフェスを使用すべきです。