Servidor MCP determinista y local-first para IDA Pro/Home: 109 operaciones de ingeniería inversa con esquema estricto, hallazgos respaldados por evidencia y ediciones de IDB controladas por políticas.
IDA Pro MCP es un servidor local del Protocolo de Contexto de Modelo (MCP) para IDA Pro. Permite que un cliente MCP inspeccione un IDB, solicite a IDA resultados de análisis deterministas y, cuando se permite explícitamente, escriba anotaciones u otros cambios de vuelta en el IDB. El proceso anfitrión se ejecuta fuera de IDA e inicia un proceso IDA headless separado para cada sesión de forma predeterminada.
ida_* con esquema estricto y descubrimiento en vivo a través de tools/list e ida_help.La versión actual es 1.0.0a3. Este es software alfa. Los nombres de operaciones públicas ida_*, los esquemas y el formato del espacio de trabajo pueden cambiar antes de una versión estable 1.0.0. La superficie de cliente predeterminada contiene 109 operaciones con esquema exacto. Utilice el descubrimiento en vivo para obtener el contrato completo: tools/list enumera cada operación con su esquema, e ida_help(topic="...") devuelve los argumentos exactos y un ejemplo para una operación.
Necesita:
idat/idat64 utilizable. La evidencia de pruebas en vivo del repositorio cubre IDA 9.3 y 9.4; 9.2 es el mínimo de compatibilidad declarado.El análisis normal no requiere un modelo de lenguaje ni un modelo de embeddings. Las funciones opcionales de búsqueda semántica utilizan un modelo local de forma predeterminada y permanecen deshabilitadas cuando no se configura ningún modelo.
El runtime predeterminado es idat: un proceso IDA headless por sesión. El backend idalib es experimental, requiere una instalación de IDA 9.3 o posterior con el paquete idapro activado, y no es necesario para una primera instalación.
El instalador crea un entorno gestionado bajo la raíz de instalación, instala una copia congelada del checkout en él y escribe la configuración del cliente para las ubicaciones de cliente soportadas. Desde la raíz del repositorio, ejecute:
python3 install.py
Para una instalación conocida de IDA, pásala explícitamente:
python3 install.py --ida-dir /path/to/ida-pro-9.3
Para una ejecución no interactiva:
python3 install.py --yes --no-ida-prompt --ida-dir /path/to/ida-pro-9.3
El instalador también puede encontrar IDA a través de IDADIR, IDA_DIR, los ejecutables de IDA en PATH y directorios de instalación comunes. --ida-version selecciona una versión cuando hay más de una instalación presente. Use --dry-run para inspeccionar primero los cambios planificados.
El instalador no descarga un modelo de embeddings a menos que usted seleccione o solicite uno. Puede crear o actualizar archivos de configuración para cada ubicación de cliente en su mapa de clientes integrado, incluidos los clientes que no están instalados en su máquina. Revise install-report.json en la raíz de instalación y elimine las entradas no utilizadas si es necesario. Los archivos de configuración regulares existentes se respaldan antes de modificarlos; los archivos malformados, con enlaces simbólicos o no regulares se rechazan en lugar de sobrescribirse.
Reinicie el cliente MCP después de la instalación para que recargue su configuración.
Los arneses de agentes descubren la superficie de herramientas en vivo: tools/list enumera cada operación con su esquema, e ida_help(topic="...") devuelve los argumentos exactos y un ejemplo. No se instalan archivos de habilidades estáticos.
La raíz de instalación predeterminada es:
~/.local/share/ida-pro-mcp%LOCALAPPDATA%/ida-pro-mcpEstablezca IDA_PRO_MCP_HOME o pase --install-root para elegir otra ubicación.
Las versiones alfa son construidas por GitHub Actions y publicadas manualmente como pre-releases. Cuando haya una versión disponible, descargue el activo bundle.zip o bundle.tar.gz y su archivo SHA256SUMS desde la
página de releases. Verifique la suma de comprobación, extraiga el paquete y ejecute el instalador desde su directorio de nivel superior:
python3 install.py --yes --no-ida-prompt --ida-dir /path/to/ida-pro-9.3
La versión también contiene una wheel y una distribución de código fuente para instalaciones Python automatizadas. El paquete es la ruta más sencilla porque incluye el instalador y todos los archivos del proyecto necesarios para configurar un cliente MCP. Las versiones son de calidad alfa; conserve el binario original y el IDB y lea las notas de la versión antes de actualizar.
El instalador escribe la entrada del servidor para las rutas de configuración de cliente que conoce. Soporta Gemini CLI, Antigravity, Antigravity IDE, Antigravity CLI, Claude Code, Codex, Copilot CLI, OpenCode, Claude Desktop, Cursor, VS Code, Windsurf, Cline y Roo Code. OpenCode y los clientes de la familia Copilot utilizan formatos de configuración diferentes; deje que el instalador escriba esos archivos o siga la guía de configuración de OpenCode.
Para un cliente que utiliza el formato JSON común, la entrada es equivalente a:
{
"mcpServers": {
"ida-pro-mcp": {
"command": "/path/to/ida-pro-mcp/.venv/bin/python",
"args": ["-u", "-m", "ida_pro_mcp.host.server"],
"env": {
"IDA_PRO_MCP_HOME": "/path/to/ida-pro-mcp",
"IDADIR": "/path/to/ida-pro-9.3",
"IDA_MCP_TOOL_SURFACE": "agent"
}
}
}
}
En Windows, use el intérprete gestionado en
<install-root>/.venv/Scripts/python.exe. Los detalles importantes son el intérprete gestionado, -u -m ida_pro_mcp.host.server, el directorio de IDA seleccionado y IDA_MCP_TOOL_SURFACE=agent. No apunte el cliente a install.py; ese archivo es el instalador, no el servidor MCP.
Después de cambiar la configuración de un cliente, reinicie completamente el cliente y verifique que ida_help aparezca en sus operaciones disponibles. Si el cliente muestra solo una interfaz heredada amplia tool(action=...), verifique que el entorno seleccione la superficie predeterminada agent en lugar de
IDA_MCP_TOOL_SURFACE=legacy.
Use primero una ruta absoluta a un binario de prueba. Abrir un binario normalmente espera a que finalice el análisis inicial de IDA; un binario grande puede tardar.
ida_open_binary(binary_path="/absolute/path/to/sample")
ida_session_status()
ida_overview()
ida_list_imports(limit=30)
ida_list_strings(query="http", limit=30)
ida_find(query="main", limit=20)
ida_decompile(address="<address returned by IDA>")
ida_xrefs_to(address="<same address>")
Use ida_help(topic="ida_decompile") siempre que necesite el esquema exacto de argumentos. Los esquemas de operaciones públicas son estrictos: los argumentos desconocidos se rechazan. Las direcciones pueden aceptarse como enteros o cadenas según el contrato de cada operación; use la forma mostrada por ida_help para la operación en su cliente.
Para un registro de investigación pequeño, las operaciones de hallazgos del espacio de trabajo son:
ida_write_finding(title="Input reaches parser", address="<address returned by IDA>", kind="finding", status="confirmed", confidence=0.8, evidence=[{"type":"call", "value":"recv", "address":"<evidence address>"}])
ida_analysis_brief()
ida_next_target()
ida_export_findings(format="markdown")
Los hallazgos del espacio de trabajo se mantienen separados de las ediciones del IDB. Si la política activa permite la escritura en el espacio de trabajo, ida_write_finding registra un hallazgo localmente; de lo contrario, el servidor devuelve un error de política. ida_publish_findings(dry_run=true) previsualiza los cambios en el IDB. La publicación, el renombrado, el parcheo y otras mutaciones del IDB están sujetas a políticas y requieren el reconocimiento documentado de la operación donde la operación lo exponga.
La página principal se mantiene orientada a tareas, pero este índice compacto facilita el escaneo de la superficie pública. Cada nombre a continuación lleva el prefijo ida_ cuando se llama. Los esquemas y ejemplos completos están disponibles en vivo a través de tools/list e ida_help(topic="...").
| Grupo | Operaciones |
|---|---|
| Sesión | open_binary, open_background, session_state, session_status, session_health, close_session, session_get, session_list, sso_activate, agent_login, agent_logout, session_switch |
| Descubrimiento | overview, find, semantic_search, reranker_status, function_families, index_functions, index_status, cancel_index, list_functions, list_strings, list_imports, list_types, list_segments, list_sigs, sreg_get, sreg_list, auto_wait, events, registers, search_data_value, search_query_lang, r2_status, r2_bininfo, r2_load_hints, r2_disassemble_hypothesis, r2_vxrefs, fw_detect_vector_table, fw_detect_load_base, fw_detect_mmio, fw_rtos_scan, fw_carve |
| Código | decompile, disassemble, compare_functions, diff_sessions, xrefs_to, callers, callees, read_bytes, get_type, callgraph, emulate |
| Hallazgos |
La política base del servidor es assist. Una sesión puede endurecer la política base del operador pero no puede relajarla. La política es determinista; no decide que una operación riesgosa es segura porque un cliente la solicite.
La inspección de solo lectura es el punto de partida normal. Los ejemplos incluyen
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 y las operaciones de cálculo. Estas aún consumen archivos locales y recursos de IDA, y el cliente MCP recibe sus resultados.
Las siguientes acciones cambian el estado duradero o ejecutan código y deben tratarse como de alto impacto:
ida_rename, ida_comment, ida_patch_bytes, cambios de función/tipo/segmento/datos, aplicación de firmas, ida_save_idb, instantáneas y operaciones de deshacer/restaurar pueden cambiar el IDB o el estado relacionado.ida_publish_findings escribe hallazgos en el IDB. Ejecute primero su forma de simulación; la forma no simulada está protegida.ida_close_session desmonta el runtime de IDA en vivo y es destructiva desde el punto de vista de la sesión.ida_python ejecuta Python arbitrario en el proceso IDA activo. Está bloqueado en modo seguro y requiere un reconocimiento explícito de riesgo bajo la política normal.ida_emulate es útil para comprobaciones controladas, pero las acciones mutantes del emulador requieren el reconocimiento correspondiente.ida_til_export e ida_til_import acceden al sistema de archivos y están protegidas. Las rutas del sistema de archivos están restringidas por la raíz de memoria configurada donde se aplica esa protección.No use --disable-policy como un indicador de conveniencia. Establece
IDA_MCP_POLICY_MODE=off y deshabilita todas las puertas de política, incluidos los reconocimientos de escritura y otros controles de flujo de trabajo. Si se deniega una llamada, lea la entrada ida_help de la operación y proporcione el argumento de reconocimiento exacto solo cuando el esquema de esa operación lo soporte.
Mientras IDA aún realiza el análisis inicial, el modo seguro bloquea algunos análisis de binario completo, indexación y operaciones de script. Está destinado a mantener las llamadas de sesión temprana limitadas; sondee ida_session_status o
ida_session_health en lugar de eludir la protección.
El puente escucha en loopback y utiliza un token por sesión. No es un servicio de red: no exponga ni reenvíe el puerto del puente a una red no confiable. Trate los scripts importados, rastros, binarios, datos de corpus y solicitudes de clientes como entrada no confiable.
La ruta normal de host a IDA es local. El proyecto no ejecuta un servicio LLM integrado en la ruta de análisis, y la incrustación local es opcional. Eso no hace que todo el flujo de trabajo sea automáticamente offline:
llama-server, las descargas opcionales de corpus de amenazas y las integraciones externas de Rizin/radare2 pueden realizar solicitudes de red cuando están habilitadas.Para una configuración solo local, use el runtime local predeterminado, deje Gemini y otras descargas opcionales deshabilitadas, y configure el cliente MCP y su modelo según la política de datos de su organización. "Solo local" aún requiere verificar qué envía el cliente a su propio proveedor de modelo.
Pase el directorio de instalación explícitamente:
python3 install.py --ida-dir /path/to/ida-pro-9.3
También puede establecer IDADIR o IDA_DIR. Si se encuentran varias instalaciones, use --ida-version 9.3 o --no-ida-prompt para controlar la selección. Confirme que el directorio seleccionado contiene un idat o idat64 ejecutable.
Reinicie el cliente e inspeccione su entrada de configuración. Confirme que su comando usa el Python del venv gestionado y -u -m ida_pro_mcp.host.server, y que el bloque env contiene el IDADIR correcto. Revise
install-report.json; el instalador registra los fallos de actualización del cliente y mantiene copias de seguridad junto a los archivos modificados. Las formas de configuración de OpenCode y la familia Copilot difieren del ejemplo JSON común.
La llamada normal ida_open_binary espera el análisis inicial. Verifique
ida_session_status e ida_session_health, permita más tiempo para un binario grande y revise los registros por sesión bajo el directorio de instalación/datos. La operación de apertura en segundo plano está disponible, pero está destinada a casos en los que comprende su comportamiento asíncrono y las restricciones del modo seguro.
Esto suele ser la política funcionando según lo configurado. Use ida_help para inspeccionar el esquema exacto de la operación y su requisito de reconocimiento. No agregue argumentos arbitrarios: los esquemas son estrictos. Revise IDA_MCP_POLICY_MODE y el archivo de política del operador antes de cambiar la política. Deshabilitar todas las puertas de política es una elección separada y deliberadamente insegura.
La búsqueda semántica es opcional y requiere un índice y un backend de embeddings compatible. El listado ordinario, la búsqueda, la descompilación y el trabajo de referencias cruzadas no la requieren. Para configurar la ruta local opcional, use las opciones explícitas de embedder del instalador, por ejemplo:
python3 install.py --setup-embedder
El instalador también puede ejecutar --embedder-doctor, usar una ruta de modelo explícita o descargar un modelo seleccionado y llama-server cuando se solicite. Las licencias de modelos, el uso de disco y las descargas de red son su responsabilidad. Si falta el modelo, el servidor debe informar que la búsqueda semántica no está disponible en lugar de pretender que se ejecutó.
Corrija la sintaxis JSON, JSONC o TOML reportada y vuelva a ejecutar el instalador. También rechaza rutas de configuración con enlaces simbólicos y no regulares para evitar sobrescribir un objetivo inesperado. Los archivos regulares existentes se respaldan; el comportamiento de reversión predeterminado del instalador puede restaurar esos respaldos si falla una fase posterior.
Verifique ida_session_health, el registro de sesión y el registro del puente. Confirme que el cliente usa la misma raíz de instalación y IDADIR que el instalador registró. El backend idat predeterminado da a cada sesión su propio proceso; no cambie al experimental idalib mientras diagnostica una instalación básica.
tools/list e ida_help exponen cada operación pública, esquema y ejemplo.Para nombres exactos de operaciones, use la referencia generada o pregunte al servidor en ejecución con ida_help. El backend anterior tool(action=...) permanece disponible por compatibilidad y se selecciona con IDA_MCP_TOOL_SURFACE=legacy; las nuevas integraciones deben usar la superficie ida_* con esquema exacto.
write_finding, mark_examined, list_findings, search_findings, update_finding, export_findings, publish_findings, import_annotations, analysis_brief, next_target |
| Edición | create_function, change_function, rename, comment, patch_bytes, save_idb, make_code, undefine, rename_local, declare_type, apply_type, add_segment, set_segment_attrs, apply_sig, sreg_set, create_data, create_strlit, undo_begin, undo_end, add_entry, idb_snapshot, idb_restore_snapshot, struct_member_add, struct_member_del, struct_member_rename, struct_member_set_type, enum_member_add, enum_member_rename, enum_member_revalue, til_delete, til_export, til_import, mark_dangerous |
| Cálculo | calc_eval, calc_offset, calc_convert, calc_resolve, calc_deref, calc_chain, calc_align, calc_bitops |
| Soporte | python, continue, help |
| Flujo de trabajo | batch |