Servidor MCP determinístico e local-first para IDA Pro/Home: 109 operações de engenharia reversa com esquema estrito, descobertas respaldadas por evidências e edições de IDB controladas por políticas.
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 IDA headless separado para cada sessão por padrão.
ida_* com esquema estrito e descoberta ao vivo através de tools/list e ida_help.A versão atual é 1.0.0a3. Este é um software alpha. Os nomes públicos das operações ida_*, os esquemas e o formato do workspace podem mudar antes de uma versão estável 1.0.0. A superfície padrão do cliente contém 109 operações com esquema exato. Use a descoberta ao vivo 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.
Você precisa de:
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.A análise normal não requer um modelo de linguagem ou um modelo de embedding. Os recursos opcionais de busca semântica usam um modelo local por padrão e permanecem desabilitados quando nenhum modelo está configurado.
O runtime padrão é idat: um processo IDA headless 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.
O instalador cria um ambiente gerenciado sob a raiz de instalação, instala uma cópia congelada do checkout nele e grava a configuração do cliente para os locais de cliente 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 através de IDADIR, IDA_DIR, dos executáveis do IDA no PATH e de 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 não baixa um modelo de embedding a menos que você selecione ou solicite um. Ele pode criar ou atualizar arquivos de configuração para cada local de cliente em seu mapa de clientes embutido, 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 como backup antes de serem alterados; arquivos malformados, symlinks 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 agente descobrem a superfície de ferramentas ao vivo: tools/list enumera cada operação com seu esquema, e ida_help(topic="...") retorna argumentos exatos e um exemplo. Nenhum arquivo de skill estático é instalado.
A raiz de instalação padrão é:
~/.local/share/ida-pro-mcp%LOCALAPPDATA%/ida-pro-mcpDefina IDA_PRO_MCP_HOME ou passe --install-root para escolher outro local.
As versões alpha são construídas pelo GitHub Actions e publicadas manualmente como pré-releases. Quando uma release estiver disponível, baixe o asset bundle.zip ou bundle.tar.gz e seu arquivo SHA256SUMS da
página de releases. Verifique o checksum, extraia o bundle e execute o instalador a partir de seu diretório de nível superior:
python3 install.py --yes --no-ida-prompt --ida-dir /path/to/ida-pro-9.3
A release também contém um wheel e uma distribuição de código-fonte para instalações Python scriptadas. O bundle é a rota mais simples porque inclui o instalador e todos os arquivos do projeto necessários para configurar um cliente MCP. As releases são de qualidade alpha; mantenha o binário original e o IDB e leia as notas de release antes de atualizar.
O instalador grava a entrada do servidor para os caminhos de configuração de 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. OpenCode e clientes 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 do IDA selecionado e IDA_MCP_TOOL_SURFACE=agent. Não aponte o cliente para install.py; esse arquivo é o instalador, não o servidor MCP.
Depois de alterar uma configuração de 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.
Use um caminho absoluto para um binário de teste primeiro. Abrir um binário normalmente aguarda 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 de argumentos exato. Os esquemas públicos das 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 em seu cliente.
Para um pequeno registro de investigação, as operações de achados 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")
Os achados do workspace são mantidos separadamente das edições do IDB. Se a política ativa permitir a gravação no workspace, ida_write_finding registra um achado localmente; caso contrário, o servidor retorna um erro de política. ida_publish_findings(dry_run=true) pré-visualiza as 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.
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, 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 |
| Achados |
A política padrão do servidor é assist. Uma sessão pode restringir a política padrão do operador, mas não pode relaxá-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 ações a seguir alteram 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 estado relacionado.ida_publish_findings grava achados no IDB. Execute primeiro sua forma dry-run; a forma não dry-run é controlada.ida_close_session derruba o runtime ativo do IDA e é destrutiva do ponto de vista da sessão.ida_python executa Python arbitrário no processo IDA ativo. É bloqueado no modo seguro e requer um reconhecimento explícito de risco sob a política normal.ida_emulate é útil para verificações controladas, mas ações mutantes do emulador requerem o reconhecimento correspondente.ida_til_export e ida_til_import acessam o sistema de arquivos e são controladas. Caminhos do sistema de arquivos são restringidos pela raiz de memória configurada onde essa proteção se aplica.Não use --disable-policy como uma flag de conveniência. Ela define
IDA_MCP_POLICY_MODE=off e desabilita todos os portões de política, incluindo reconhecimentos de gravação e outros controles de fluxo de trabalho. Se uma chamada for negada, leia a entrada ida_help da operação e forneça o argumento de reconhecimento exato apenas 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 de binário completo, indexação e script. Ele se destina a manter as chamadas de sessão inicial restritas; faça polling de 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. 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, traces, binários, dados de corpus e solicitações de cliente como entrada não confiável.
O caminho normal host-para-IDA é local. O projeto não executa um serviço LLM embutido no caminho de análise, e o embedding local é opt-in. Isso não torna todo o fluxo de trabalho automaticamente offline:
llama-server, downloads opcionais de corpus de ameaças e integrações externas Rizin/radare2 podem fazer solicitações de rede quando habilitados.Para uma configuração somente local, use o runtime local padrão, deixe o Gemini e outros downloads opcionais desabilitados, e configure o cliente MCP e seu modelo de acordo com a política de dados da sua organização. "Somente local" ainda exige verificar o que o cliente envia para seu próprio provedor de modelo.
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.
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. Os formatos de configuração do OpenCode e da família Copilot diferem do exemplo JSON comum.
A chamada normal 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 destina-se a casos em que você entende seu comportamento assíncrono e as restrições do modo seguro.
Isso geralmente é a política funcionando conforme 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. Desabilitar todos os portões de política é uma escolha separada e deliberadamente insegura.
A busca semântica é opcional e requer um índice e um backend de embedding compatível. Listagem comum, busca, descompilação e trabalho de referência cruzada não a requerem. Para configurar o caminho local opcional, use as opções explícitas de embedder do instalador, por exemplo:
python3 install.py --setup-embedder
O instalador também pode executar --embedder-doctor, usar um caminho de modelo explícito ou baixar um modelo selecionado e llama-server quando solicitado. Licenças de modelo, uso de disco e downloads de rede são sua responsabilidade. Se o modelo estiver ausente, o servidor deve relatar a busca semântica como indisponível em vez de fingir que ela foi executada.
Corrija a sintaxe JSON, JSONC ou TOML relatada e execute o instalador novamente. Ele também recusa caminhos de configuração com symlink e não regulares para evitar sobrescrever um alvo inesperado. Arquivos regulares existentes são copiados como backup; o comportamento de rollback padrão do instalador pode restaurar esses backups se uma fase posterior falhar.
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 idat dá a cada sessão seu próprio processo; não mude para o experimental idalib enquanto diagnostica uma instalação básica.
tools/list e
ida_help expõem cada operação pública, esquema e exemplo.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 ida_* com esquema exato.
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, 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 |