IDA Pro MCP

IDA Pro MCP

⚠️ Archivado — reemplazado por el servidor oficial Hex-Rays IDA MCP

Este proyecto ya no se mantiene. El 2026-09-27, Hex-Rays SA publicó el Servidor Oficial IDA MCP y IDA Nexus. El desarrollo se detuvo el mismo día en 1.0.0a4.

Para uso actual, instala el suyo: uvx ida-hcli mcp install. Requiere IDA 9.4+ con idalib y funciona completamente sin interfaz gráfica; el plugin de GUI es opcional.

Este repositorio se conserva por su suite de pruebas, documentación y registro arquitectónico. Consulta ARCHIVE.md para el informe completo de cierre: qué era el proyecto, por qué perdió, qué partes eran andamiaje y qué partes aún valen algo. El resto de este README describe un sistema que ya no se recomienda usar.

IDA Pro MCP es un servidor local del Model Context Protocol 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 al IDB. El proceso host se ejecuta fuera de IDA e inicia un proceso separado de IDA sin interfaz gráfica para cada sesión de forma predeterminada.

Por qué esta implementación

• Superficie de agente determinista: 102 operaciones ida_* con esquema estricto con descubrimiento en vivo a través de tools/list y ida_help.
• Arquitectura local primero: el host y el runtime de IDA se comunican a través de un puente de loopback protegido por token; ningún servicio LLM oculto se encuentra en la ruta de análisis.
• Evidencia, no solo chat: los hallazgos duraderos preservan procedencia, confianza, estado del ciclo de vida, conflictos e historial de auditoría fuera del IDB.
• Mutaciones protegidas: las operaciones que cambian el IDB permanecen detrás de controles explícitos de política y reconocimiento de riesgo.
• Amplio soporte de clientes: el instalador comprende más de 22 entornos de agentes y sus formas de configuración JSON, JSON5, TOML y YAML.

La versión actual es 1.0.0a4. Este es software alfa. Los nombres públicos de operaciones ida_*, esquemas y formato de workspace pueden cambiar antes de un lanzamiento estable 1.0.0. La superficie de cliente predeterminada contiene 102 operaciones de esquema exacto. Usa el descubrimiento en vivo para el contrato completo: tools/list enumera cada operación con su esquema, y ida_help(topic="...") devuelve los argumentos exactos y un ejemplo para una operación.

Antes de instalar

Necesitas:

• IDA Pro o IDA Home 9.2 o más reciente, con un ejecutable idat/idat64 utilizable. La evidencia de pruebas en vivo del repositorio cubre IDA 9.3 y 9.4; 9.2 es el piso de compatibilidad declarado.
• Python 3.11 o más reciente para el host y el instalador.
• Permiso para ejecutar IDA en los binarios que planeas inspeccionar, y suficiente espacio en disco para un entorno Python administrado, archivos de sesión y copias de IDB.
• Un cliente MCP que admita un servidor stdio local, como Claude Code, Codex, OpenCode, Claude Desktop, Cursor, VS Code/Copilot, Windsurf, Cline, Roo Code, Gemini CLI o Antigravity.

El análisis normal no requiere un proveedor de inteligencia. Los modos de inteligencia explícitos son jev, custom y disabled; el modo deshabilitado mantiene la búsqueda léxica determinista disponible y no hay respaldo local, Gemini o de modelo nativo.

El runtime predeterminado es idat: un proceso de IDA sin interfaz gráfica por sesión. El backend idalib es experimental, requiere una instalación de IDA 9.3 o más reciente con el paquete idapro activado, y no es necesario para una primera instalación.

Instalar desde el checkout del código fuente

El instalador crea un entorno administrado 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 clientes compatibles. Desde la raíz del repositorio, ejecuta:

python3 install.py

Para una instalación de IDA conocida, 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. Usa --dry-run para inspeccionar los cambios planificados primero.

El instalador nunca descarga un modelo de proveedor o runtime. Puede crear o actualizar archivos de configuración para cada ubicación de cliente en su mapa de clientes integrado, incluidos clientes que no están instalados en tu máquina. Revisa install-report.json en la raíz de instalación y elimina las entradas no utilizadas si es necesario. Los archivos de configuración regulares existentes se respaldan antes de cambiarse; los archivos malformados, con enlaces simbólicos o no regulares se rechazan en lugar de sobrescribirse.

Reinicia el cliente MCP después de la instalación para que recargue su configuración.

Los harnesses de agentes descubren la superficie de herramientas en vivo: tools/list enumera cada operación con su esquema, y ida_help(topic="...") devuelve argumentos exactos y un ejemplo. No se instalan archivos de habilidades estáticas.

La raíz de instalación predeterminada es:

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

Establece IDA_PRO_MCP_HOME o pasa --install-root para elegir otra ubicación.

Instalar desde un artefacto de lanzamiento

Los lanzamientos alfa se construyen con GitHub Actions y se publican manualmente como prelanzamientos. Cuando un lanzamiento esté disponible, descarga el activo bundle.zip o bundle.tar.gz y su archivo SHA256SUMS de la página de lanzamientos. Verifica la suma de verificación, extrae el paquete y ejecuta el instalador desde su directorio de nivel superior:

python3 install.py --yes --no-ida-prompt --ida-dir /path/to/ida-pro-9.3

El lanzamiento también contiene una wheel y una distribución de código fuente para instalaciones de Python con script. El paquete es la ruta más simple porque incluye el instalador y todos los archivos del proyecto necesarios para configurar un cliente MCP. Los lanzamientos son de calidad alfa; conserva el binario original y el IDB y lee las notas del lanzamiento antes de actualizar.

Conectar un cliente MCP

El instalador escribe la entrada del servidor para las rutas de configuración del cliente que conoce. Admite 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 usan formas de configuración diferentes; deja que el instalador escriba esos archivos o sigue la guía de configuración de OpenCode.

Para un cliente que usa 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, usa el intérprete administrado en <install-root>/.venv/Scripts/python.exe. Los detalles importantes son el intérprete administrado, -u -m ida_pro_mcp.host.server, el directorio de IDA seleccionado y IDA_MCP_TOOL_SURFACE=agent. No apuntes el cliente a install.py; ese archivo es el instalador, no el servidor MCP.

Después de cambiar una configuración de cliente, reinicia completamente el cliente y verifica que ida_help aparezca en sus operaciones disponibles. Si el cliente muestra solo una interfaz heredada amplia tool(action=...), verifica que el entorno seleccione la superficie predeterminada agent en lugar de IDA_MCP_TOOL_SURFACE=legacy.

Una primera sesión útil

Usa una ruta absoluta a un binario de prueba primero. Abrir un binario normalmente espera a que termine el análisis inicial de IDA; un binario grande puede tomar tiempo.

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>")

Usa ida_help(topic="ida_decompile") siempre que necesites el esquema de argumentos exacto. 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 la operación individual; usa la forma mostrada por ida_help para la operación en tu cliente.

Para un registro de investigación pequeño, las operaciones de hallazgos del workspace 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 workspace se mantienen separados de las ediciones del IDB. Si la política activa permite la escritura del workspace, 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 del IDB. Publicar, renombrar, parchear y otras mutaciones del IDB están sujetas a política y requieren el reconocimiento documentado de la operación donde la operación lo expone.

Operaciones de un vistazo

La página principal se mantiene orientada a tareas, pero este índice compacto mantiene la superficie pública fácil de escanear. Cada nombre a continuación se prefija con ida_ al llamarse. Los esquemas y ejemplos completos están disponibles en vivo a través de tools/list y 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, intelligence_status, usage_status, usage_report, reranker_status, 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
Inteligencia	intelligence_status, usage_status, usage_report
Código	decompile, disassemble, compare_functions, diff_sessions, xrefs_to, callers, callees, read_bytes, get_type, callgraph, emulate
Hallazgos	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, import_system_map, 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

Qué es seguro y qué no

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 sea segura porque un cliente lo solicite.

La inspección de solo lectura es el punto de partida normal. 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 modificar el IDB o el estado relacionado.
• ida_publish_findings escribe hallazgos en el IDB. Ejecute primero su forma de prueba en seco; la forma que no es de prueba en seco está restringida.
• ida_close_session derriba el runtime de IDA en vivo y es destructivo desde el punto de vista de la sesión.
• ida_python ejecuta Python arbitrario en el proceso de 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 de emulador que mutan requieren el reconocimiento correspondiente.
• ida_til_export y ida_til_import acceden al sistema de archivos y están restringidos. Las rutas del sistema de archivos están limitadas por la raíz de memoria configurada donde se aplica esa protección.

No use --disable-policy como una bandera de conveniencia. Establece IDA_MCP_POLICY_MODE=off y desactiva todas las puertas de política, incluidos los reconocimientos de escritura y otros controles de flujo de trabajo. Si una llamada es denegada, lea la entrada de ida_help de la operación y proporcione el argumento reconocido exacto solo cuando el esquema de esa operación lo admita.

Mientras IDA aún realiza el análisis inicial, el modo seguro bloquea algunas operaciones de análisis de binarios completos, indexación y scripts. Está diseñado para mantener las llamadas de sesión temprana limitadas; consulte ida_session_status o ida_session_health en lugar de eludir la protección.

El puente escucha en loopback y usa 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, trazas, binarios, datos de corpus y solicitudes de clientes como entrada no confiable.

Privacidad y manejo de datos

La ruta normal de host a IDA es local. El proyecto no ejecuta un servicio LLM integrado en la ruta de análisis. La inteligencia es Jev explícito, BYOK personalizado o deshabilitado; el modo deshabilitado es completamente offline. Un proveedor remoto configurado aún hace visibles en la red las solicitudes de asesoría seleccionadas:

• El cliente MCP conectado recibe rutas, símbolos, cadenas, bytes, descompilación, hallazgos y otros resultados. El cliente o su proveedor de modelo puede transmitir ese contexto según su propia cuenta, modelo y configuración de retención. IDA Pro MCP no puede controlar esas transferencias.
• Jev y los proveedores personalizados reciben solo estado de preguntas tipadas limitado (choice / noul / score) a través de HTTP del host: metadatos, muestras de bytes/desensamblado y firmas compactas. La descompilación cruda, los prompts, las completaciones y las credenciales no se registran ni persisten. Las respuestas no pueden autorizar mutaciones, satisfacer risk_ack ni escribir hallazgos en el blackboard; los fallos cierran en orden léxico. La etapa de asesoría compartida puede evaluar un vecindario de función limitado en una solicitud y sugerir una siguiente llamada determinista de ida_*; el llamador decide si ejecutarla. Jev sigue siendo opcional y las herramientas neutrales de proveedor siguen utilizables en modo deshabilitado; consulte Intelligence.
• Los orígenes de nube personalizados requieren una lista de permitidos HTTPS explícita. HTTP simple se acepta solo para endpoints de loopback cuando se habilita explícitamente.
• Las descargas de dependencias del instalador y las descargas opcionales de corpus de amenazas pueden hacer solicitudes de red cuando están habilitadas.
• La caché local, los registros, los metadatos de sesión, los IDB administrados y el blackboard pueden contener rutas, metadatos de análisis y hallazgos. Proteja los directorios de instalación/datos. Las credenciales se leen en el momento de la solicitud y nunca se escriben en la configuración generada del cliente.

Para una configuración solo local, seleccione --intelligence-mode disabled. El análisis determinista de IDA, la indexación/búsqueda léxica, el almacenamiento y los controles de política siguen disponibles sin un proveedor.

Solución de problemas común

El instalador no puede encontrar IDA

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.

El cliente no muestra IDA Pro MCP

Reinicie el cliente e inspeccione su entrada de configuración. Confirme que su comando usa el Python del venv administrado y -u -m ida_pro_mcp.host.server, y que el bloque env contiene el IDADIR correcto. Revise install-report.json; el instalador registra 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.

Abrir un binario tarda mucho o parece atascado

La llamada normal de ida_open_binary espera el análisis inicial. Verifique ida_session_status y 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 donde entienda su comportamiento asíncrono y las restricciones del modo seguro.

Una operación de escritura es denegada

Esto suele ser la política funcionando como está configurada. 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, deliberadamente insegura.

La inteligencia o la búsqueda semántica no está disponible

La búsqueda semántica usa firmas léxicas deterministas y no requiere un proveedor. La puntuación opcional de Jev/personalizada es de asesoría; una clave faltante, una interrupción del proveedor, una respuesta malformada o un presupuesto agotado devuelven un error estructurado del proveedor mientras los resultados léxicos siguen disponibles. Configure Jev o personalizado explícitamente con --intelligence-mode y las variables documentadas de IDA_MCP_*; no hay respaldo de modelo local.

El instalador rechaza una configuración de cliente

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 destino inesperado. Los archivos regulares existentes se respaldan; el comportamiento de reversión predeterminado del instalador puede restaurar esas copias si una fase posterior falla.

Una sesión o runtime de IDA falla

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 predeterminado de idat da a cada sesión su propio proceso; no cambie al idalib experimental mientras diagnostica una instalación básica.

Pruebas y cobertura (offline)

La suite offline (pytest --ignore=tests/integration) es la puerta predeterminada. Al 2026-09-27 EEST: 5491 aprobadas / 6 omitidas (~4m04s); cobertura de línea offline de src/ 95.88% (56,110 stmts / 2,309 miss) — objetivo de >=90% de src/ cumplido. La suite también pasa limpia con -W error::DeprecationWarning, por lo que la puerta no depende del comportamiento de importación obsoleto. La cifra de la Fase 0 de la Encuesta de 64.27% es solo histórica (PROJECT.md). Las comprobaciones remotas de IDA en vivo y Jev opcional siguen opt-in; consulte AGENTS.md y Pruebas de IDA en vivo.

Material de referencia

• Wiki del proyecto — guías orientadas a tareas de instalación, investigación, edición y solución de problemas.
• Páginas wiki locales — el mismo material escrito a mano incluido para la herramienta wiki integrada.
• Descubrimiento de operaciones en vivo — tools/list y ida_help exponen cada operación pública, esquema y ejemplo.
• Modelo de seguridad — límites de confianza, modos de política, transporte loopback, propiedad de sesión y protecciones del sistema de archivos.
• Espacio de trabajo de investigación — hallazgos, evidencia, objetivos y exportaciones.
• Inteligencia y proveedores — Jev, BYOK personalizado, modo deshabilitado, presupuestos de uso, recuperación léxica y asesorías de investigación compartidas.
• Configuración de OpenCode — configuración de OpenCode.
• Arquitectura — host, runtime de IDA y flujo de datos para lectores que necesitan detalle de implementación.
• Política de seguridad — guía de reporte y seguridad.
• Pruebas de IDA en vivo — qué las pruebas del repositorio demuestran y no demuestran sobre una instalación real de IDA.
• Versionado y lista de verificación de lanzamiento y el registro de cambios — estado alfa e historial de lanzamientos.
• Índice de documentación — el mapa completo de guías mantenidas, referencias, páginas wiki y notas de investigación.

Para nombres exactos de operaciones, use la referencia generada o pregunte al servidor en ejecución con ida_help. El backend más antiguo de tool(action=...) sigue disponible para compatibilidad y se selecciona con IDA_MCP_TOOL_SURFACE=legacy; las nuevas integraciones deben usar la superficie de ida_* de esquema exacto.