IDA Pro MCP

IDA Pro MCP

⚠️ Arquivado — substituído pelo servidor oficial Hex-Rays IDA MCP

Este projeto não é mais mantido. Em 27/09/2026, a Hex-Rays SA lançou o Servidor Oficial IDA MCP e o IDA Nexus. O desenvolvimento foi interrompido no mesmo dia em 1.0.0a4.

Para uso atual, instale o deles: uvx ida-hcli mcp install. Ele requer IDA 9.4+ com idalib e funciona totalmente headless; o plugin de GUI é opcional.

Este repositório é mantido por sua suíte de testes, documentação e registro arquitetural. Consulte ARCHIVE.md para o relato completo do encerramento: o que o projeto era, por que perdeu, quais partes eram andaimes e quais partes ainda têm valor. O restante deste README descreve um sistema que não é mais recomendado para uso.

O IDA Pro MCP é um servidor local do Model Context Protocol para o IDA Pro. Ele permite que um cliente MCP inspecione um IDB, solicite ao IDA resultados de análise determinísticos e, quando explicitamente permitido, grave anotações ou outras alterações de volta no IDB. O processo host é executado fora do IDA e inicia um processo headless separado do IDA para cada sessão por padrão.

Por que esta implementação

• Superfície de agente determinística: 102 operações ida_* com esquema estrito com descoberta em tempo real por meio de tools/list e ida_help.
• Arquitetura local-first: o host e o runtime do IDA se comunicam por meio de uma ponte de loopback protegida por token; nenhum serviço oculto de LLM fica no caminho da análise.
• Evidência, não apenas conversa: descobertas duráveis preservam proveniência, confiança, estado do ciclo de vida, conflitos e histórico de auditoria fora do IDB.
• Mutações protegidas: operações que alteram o IDB permanecem atrás de políticas explícitas e controles de reconhecimento de risco.
• Amplo suporte a clientes: o instalador entende mais de 22 ambientes de agentes e seus formatos de configuração JSON, JSON5, TOML e YAML.

A versão atual é 1.0.0a4. Este é um software alfa. Os nomes públicos das operações ida_*, esquemas e formato do workspace podem mudar antes de um lançamento estável 1.0.0. A superfície padrão do cliente contém 102 operações com esquema exato. Use a descoberta em tempo real para o contrato completo: tools/list enumera cada operação com seu esquema, e ida_help(topic="...") retorna os argumentos exatos e um exemplo para uma operação.

Antes de instalar

Você precisa de:

• IDA Pro ou IDA Home 9.2 ou mais recente, com um executável idat/idat64 utilizável. As evidências de teste ao vivo do repositório cobrem IDA 9.3 e 9.4; 9.2 é o piso de compatibilidade declarado.
• Python 3.11 ou mais recente para o host e o instalador.
• Permissão para executar o IDA nos binários que você planeja inspecionar e espaço em disco suficiente para um ambiente Python gerenciado, arquivos de sessão e cópias do IDB.
• Um cliente MCP que suporte um servidor stdio local, como Claude Code, Codex, OpenCode, Claude Desktop, Cursor, VS Code/Copilot, Windsurf, Cline, Roo Code, Gemini CLI ou Antigravity.

A análise normal não requer um provedor de inteligência. Os modos explícitos de inteligência são jev, custom e disabled; o modo desabilitado mantém a busca lexical determinística disponível e não há fallback local, Gemini ou modelo nativo.

O runtime padrão é idat: um processo headless do IDA por sessão. O backend idalib é experimental, requer uma instalação do IDA 9.3 ou mais recente com o pacote idapro ativado e não é necessário para uma primeira instalação.

Instalar a partir do checkout da fonte

O instalador cria um ambiente gerenciado sob o diretório raiz de instalação, instala uma cópia congelada do checkout nele e grava a configuração do cliente para os locais de clientes suportados. A partir da raiz do repositório, execute:

python3 install.py

Para uma instalação conhecida do IDA, passe-a explicitamente:

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

Para uma execução não interativa:

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

O instalador também pode encontrar o IDA por meio de IDADIR, IDA_DIR, os executáveis do IDA em PATH e diretórios de instalação comuns. --ida-version seleciona uma versão quando mais de uma instalação está presente. Use --dry-run para inspecionar as alterações planejadas primeiro.

O instalador nunca baixa um modelo de provedor ou runtime. Ele pode criar ou atualizar arquivos de configuração para cada local de cliente em seu mapa de clientes integrado, incluindo clientes que não estão instalados na sua máquina. Verifique install-report.json na raiz de instalação e remova entradas não utilizadas, se necessário. Arquivos de configuração regulares existentes são copiados em backup antes de serem alterados; arquivos malformados, com symlink ou não regulares são recusados em vez de sobrescritos.

Reinicie o cliente MCP após a instalação para que ele recarregue sua configuração.

Os harnesses de agentes descobrem a superfície de ferramentas em tempo real: tools/list enumera cada operação com seu esquema, e ida_help(topic="...") retorna argumentos exatos e um exemplo. Nenhum arquivo de habilidades estático é instalado.

A raiz de instalação padrão é:

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

Defina IDA_PRO_MCP_HOME ou passe --install-root para escolher outro local.

Instalar a partir de um artefato de lançamento

Os lançamentos alfa são construídos pelo GitHub Actions e publicados manualmente como pré-lançamentos. Quando um lançamento estiver disponível, baixe o ativo bundle.zip ou bundle.tar.gz e seu arquivo SHA256SUMS da página de lançamentos. Verifique a soma de verificação, extraia o pacote e execute o instalador a partir do diretório de nível superior:

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

O lançamento também contém uma wheel e uma distribuição de fonte para instalações Python scriptadas. O pacote é o caminho mais simples porque inclui o instalador e todos os arquivos do projeto necessários para configurar um cliente MCP. Os lançamentos são de qualidade alfa; mantenha o binário original e o IDB e leia as notas do lançamento antes de atualizar.

Conectar um cliente MCP

O instalador grava a entrada do servidor para os caminhos de configuração do cliente que conhece. Ele suporta Gemini CLI, Antigravity, Antigravity IDE, Antigravity CLI, Claude Code, Codex, Copilot CLI, OpenCode, Claude Desktop, Cursor, VS Code, Windsurf, Cline e Roo Code. Clientes OpenCode e da família Copilot usam formatos de configuração diferentes; deixe o instalador gravar esses arquivos ou siga o guia de configuração do OpenCode.

Para um cliente que usa o formato JSON comum, a entrada é 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"
      }
    }
  }
}

No Windows, use o interpretador gerenciado em <install-root>/.venv/Scripts/python.exe. Os detalhes importantes são o interpretador gerenciado, -u -m ida_pro_mcp.host.server, o diretório selecionado do IDA e IDA_MCP_TOOL_SURFACE=agent. Não aponte o cliente para install.py; esse arquivo é o instalador, não o servidor MCP.

Após alterar a configuração de um cliente, reinicie completamente o cliente e verifique se ida_help aparece em suas operações disponíveis. Se o cliente mostrar apenas uma interface legada ampla tool(action=...), verifique se o ambiente seleciona a superfície padrão agent em vez de IDA_MCP_TOOL_SURFACE=legacy.

Uma primeira sessão útil

Use um caminho absoluto para um binário de teste primeiro. Abrir um binário normalmente espera a análise inicial do IDA terminar; um binário grande pode levar tempo.

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") sempre que precisar do esquema exato de argumentos. Os esquemas públicos de operações são estritos: argumentos desconhecidos são rejeitados. Endereços podem ser aceitos como inteiros ou strings de acordo com o contrato individual da operação; use a forma mostrada por ida_help para a operação no seu cliente.

Para um pequeno registro de investigação, as operações de descobertas do workspace são:

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

As descobertas do workspace são mantidas separadamente das edições do IDB. Se a política ativa permitir a gravação no workspace, ida_write_finding registra uma descoberta localmente; caso contrário, o servidor retorna um erro de política. ida_publish_findings(dry_run=true) pré-visualiza alterações no IDB. Publicar, renomear, aplicar patches e outras mutações no IDB são controladas por política e exigem o reconhecimento documentado da operação onde a operação expõe um.

Operações em resumo

A página inicial permanece orientada a tarefas, mas este índice compacto mantém a superfície pública fácil de escanear. Cada nome abaixo é prefixado com ida_ quando chamado. Os esquemas e exemplos completos estão disponíveis ao vivo via tools/list e ida_help(topic="...").

Grupo	Operações
Sessão	open_binary, open_background, session_state, session_status, session_health, close_session, session_get, session_list, sso_activate, agent_login, agent_logout, session_switch
Descoberta	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
Inteligência	intelligence_status, usage_status, usage_report
Código	decompile, disassemble, compare_functions, diff_sessions, xrefs_to, callers, callees, read_bytes, get_type, callgraph, emulate
Descobertas	write_finding, mark_examined, list_findings, search_findings, update_finding, export_findings, publish_findings, import_annotations, analysis_brief, next_target
Edição	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
Suporte	python, continue, help
Fluxo de trabalho	batch

O que é seguro e o que não é

A política de linha de base do servidor é assist. Uma sessão pode restringir a política de linha de base do operador, mas não pode flexibilizá-la. A política é determinística; ela não decide que uma operação arriscada é segura porque um cliente a solicita.

A inspeção somente leitura é o ponto de partida normal. Exemplos incluem 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 e as operações de cálculo. Elas ainda consomem arquivos locais e recursos do IDA, e o cliente MCP recebe seus resultados.

As seguintes ações alteram o estado durável ou executam código e devem ser tratadas como de alto impacto:

• ida_rename, ida_comment, ida_patch_bytes, alterações de função/tipo/segmento/dados, aplicação de assinatura, ida_save_idb, snapshots e operações de desfazer/restaurar podem alterar o IDB ou o estado relacionado.
• ida_publish_findings grava descobertas no IDB. Execute primeiro sua forma de execução simulada (dry-run); a forma sem dry-run é controlada por permissão.
• ida_close_session encerra o runtime do IDA ativo e é destrutivo do ponto de vista da sessão.
• ida_python executa Python arbitrário no processo IDA ativo. Ele é bloqueado no modo seguro e exige reconhecimento explícito de risco sob a política normal.
• ida_emulate é útil para verificações controladas, mas ações de emulação que mutam estado exigem o reconhecimento correspondente.
• ida_til_export e ida_til_import acessam o sistema de arquivos e são controlados por permissão. Os caminhos do sistema de arquivos são restritos pela raiz de memória configurada quando essa proteção se aplica.

Não use --disable-policy como um sinalizador de conveniência. Ele define IDA_MCP_POLICY_MODE=off e desativa todos os portões de política, incluindo reconhecimentos de escrita e outros controles de fluxo de trabalho. Se uma chamada for negada, leia a entrada de ida_help da operação e forneça o argumento reconhecido exato somente quando o esquema dessa operação o suportar.

Enquanto o IDA ainda está realizando a análise inicial, o modo seguro bloqueia algumas operações de análise completa do binário, indexação e script. Ele tem a intenção de manter as chamadas no início da sessão limitadas; consulte ida_session_status ou ida_session_health em vez de contornar a proteção.

A ponte escuta em loopback e usa um token por sessão. Ela não é um serviço de rede: não exponha nem encaminhe a porta da ponte para uma rede não confiável. Trate scripts importados, rastros, binários, dados de corpus e solicitações de clientes como entrada não confiável.

Privacidade e tratamento de dados

O caminho normal host-para-IDA é local. O projeto não executa um serviço de LLM embutido no caminho de análise. A inteligência é Jev explícito, BYOK personalizado ou desativada; o modo desativado é totalmente offline. Um provedor remoto configurado ainda torna as solicitações de assessoria selecionadas visíveis na rede:

• O cliente MCP conectado recebe caminhos, símbolos, strings, bytes, descompilação, descobertas e outros resultados. O cliente ou seu provedor de modelo pode transmitir esse contexto de acordo com suas próprias configurações de conta, modelo e retenção. O IDA Pro MCP não pode controlar essas transferências.
• Jev e provedores personalizados recebem apenas estado limitado de perguntas tipadas (choice / noul / score) via HTTP do lado do host: metadados, amostras de bytes/desmontagem e assinaturas compactas. Descompilação bruta, prompts, conclusões e credenciais não são registrados nem persistidos. Respostas não podem autorizar mutações, satisfazer risk_ack ou gravar descobertas no blackboard; falhas fecham em ordem lexical. O estágio de assessoria compartilhado pode avaliar uma vizinhança limitada de função em uma solicitação e sugerir uma próxima chamada determinística de ida_*; o chamador decide se a executa. O Jev permanece opcional e ferramentas neutras de provedor permanecem utilizáveis no modo desativado; consulte Intelligence.
• Origens personalizadas na nuvem exigem uma lista de permissões HTTPS explícita. HTTP simples é aceito apenas para endpoints de loopback quando explicitamente habilitado.
• Downloads de dependências do instalador e downloads opcionais de corpus de ameaças podem fazer solicitações de rede quando habilitados.
• Cache local, logs, metadados de sessão, IDBs gerenciados e o blackboard podem conter caminhos, metadados de análise e descobertas. Proteja os diretórios de instalação/dados. As credenciais são lidas no momento da solicitação e nunca são gravadas na configuração gerada do cliente.

Para uma configuração somente local, selecione --intelligence-mode disabled. Análise determinística do IDA, indexação/pesquisa lexical, armazenamento e controles de política permanecem disponíveis sem um provedor.

Solução de problemas comum

O instalador não encontra o IDA

Passe o diretório de instalação explicitamente:

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

Você também pode definir IDADIR ou IDA_DIR. Se várias instalações forem encontradas, use --ida-version 9.3 ou --no-ida-prompt para controlar a seleção. Confirme que o diretório selecionado contém um idat ou idat64 executável.

O cliente não mostra o IDA Pro MCP

Reinicie o cliente e inspecione sua entrada de configuração. Confirme que seu comando usa o Python do venv gerenciado e -u -m ida_pro_mcp.host.server, e que o bloco env contém o IDADIR correto. Revise install-report.json; o instalador registra falhas de atualização do cliente e mantém backups ao lado dos arquivos modificados. As formas de configuração do OpenCode e da família Copilot diferem do exemplo JSON comum.

Abrir um binário leva muito tempo ou parece travado

A chamada normal de ida_open_binary aguarda a análise inicial. Verifique ida_session_status e ida_session_health, permita mais tempo para um binário grande e verifique os logs por sessão sob o diretório de instalação/dados. A operação de abertura em segundo plano está disponível, mas é destinada a casos em que você entende seu comportamento assíncrono e as restrições do modo seguro.

Uma operação de escrita é negada

Isso geralmente é a política funcionando como configurada. Use ida_help para inspecionar o esquema exato da operação e seu requisito de reconhecimento. Não adicione argumentos arbitrários: os esquemas são estritos. Revise IDA_MCP_POLICY_MODE e o arquivo de política do operador antes de alterar a política. Desativar todos os portões de política é uma escolha separada e deliberadamente insegura.

Inteligência ou pesquisa semântica indisponível

A pesquisa semântica usa assinaturas lexicais determinísticas e não requer um provedor. A pontuação opcional de Jev/personalizada é consultiva; uma chave ausente, interrupção do provedor, resposta malformada ou orçamento esgotado retorna um erro estruturado do provedor enquanto os resultados lexicais permanecem disponíveis. Configure Jev ou personalizado explicitamente com --intelligence-mode e as variáveis documentadas de IDA_MCP_*; não há fallback de modelo local.

O instalador recusa uma configuração do cliente

Corrija a sintaxe JSON, JSONC ou TOML relatada e execute novamente o instalador. Ele também recusa caminhos de configuração com link simbólico e não regulares para evitar sobrescrever um destino inesperado. Arquivos regulares existentes são copiados em backup; o comportamento padrão de reversão do instalador pode restaurar esses backups se uma fase posterior falhar.

Uma sessão ou runtime do IDA falha

Verifique ida_session_health, o log da sessão e o log da ponte. Confirme que o cliente está usando a mesma raiz de instalação e IDADIR que o instalador registrou. O backend padrão de idat dá a cada sessão seu próprio processo; não alterne para o idalib experimental ao diagnosticar uma instalação básica.

Testes e cobertura (offline)

A suíte offline (pytest --ignore=tests/integration) é o portão padrão. Em 2026-09-27 EEST: 5491 aprovados / 6 pulados (~4m04s); cobertura de linha src/ offline 95,88% (56.110 stmts / 2.309 miss) — meta de >=90% src/ atingida. A suíte também passa limpa com -W error::DeprecationWarning, então o portão não depende de comportamento de importação obsoleto. A figura de 64,27% da Fase 0 da Pesquisa é apenas histórica (PROJECT.md). Verificações remotas ao vivo do IDA e opcionais do Jev permanecem opt-in; consulte AGENTS.md e Testes ao vivo do IDA.

Material de referência

• Wiki do projeto — guias orientados a tarefas de instalação, investigação, edição e solução de problemas.
• Páginas de wiki locais — o mesmo material escrito manualmente incluído para a ferramenta de wiki embutida.
• Descoberta de operações ao vivo — tools/list e ida_help expõem cada operação pública, esquema e exemplo.
• Modelo de segurança — limites de confiança, modos de política, transporte de loopback, propriedade de sessão e proteções de sistema de arquivos.
• Espaço de trabalho de investigação — descobertas, evidências, alvos e exportações.
• Inteligência e provedores — Jev, BYOK personalizado, modo desativado, orçamentos de uso, recuperação lexical e assessorias compartilhadas de investigação.
• Configuração do OpenCode — configuração do OpenCode.
• Arquitetura — host, runtime do IDA e fluxo de dados para leitores que precisam de detalhes de implementação.
• Política de segurança — orientação de relato e segurança.
• Testes ao vivo do IDA — o que os testes do repositório provam e não provam sobre uma instalação real do IDA.
• Versionamento e lista de verificação de lançamento e o changelog — status alfa e histórico de lançamentos.
• Índice de documentação — o mapa completo de guias mantidos, referências, páginas de wiki e notas de pesquisa.

Para nomes exatos de operações, use a referência gerada ou pergunte ao servidor em execução com ida_help. O backend mais antigo tool(action=...) permanece disponível para compatibilidade e é selecionado com IDA_MCP_TOOL_SURFACE=legacy; novas integrações devem usar a superfície de esquema exato ida_*.