IDA Pro MCP Fusion

Fusão IDA Pro MCP para engenharia reversa com 76 ferramentas, cache SQLite e análise headless multi-binário do IDA.

Documentação

Um endpoint MCP. Muitos binários. Contexto de análise persistente.

Início rápido · Por que Fusion · Arquitetura · Ferramentas · Configuração · Desenvolvimento

O que é o Fusion?

O IDA Pro MCP Fusion conecta agentes de codificação compatíveis com MCP ao IDA Pro e transforma uma única conexão em um espaço de trabalho prático de engenharia reversa. Ele combina análise ao vivo do IDA com um índice SQLite persistente e um supervisor que pode manter vários binários abertos em workers headless isolados.

Use-o para descompilar e desmontar funções, rastrear referências cruzadas, consultar tipos, renomear símbolos, aplicar patches em dados, criar assinaturas, inspecionar múltiplas amostras e reutilizar análise em cache sem percorrer repetidamente as APIs single-threaded do IDA.

[!IMPORTANT] Este projeto requer uma instalação local licenciada do IDA Pro. O IDA Free não é suportado. O servidor não fornece IDA, Hex-Rays ou um serviço de análise hospedado.

Por que Fusion

	Capacidade	O que muda
⚡	Cache SQLite persistente	Funções, strings, globais, imports, xrefs e arestas do grafo de chamadas permanecem consultáveis em investigações repetidas.
◈	Supervisor multi-binário	Abra, enderece e feche vários bancos de dados GUI ou headless por meio de um único endpoint MCP.
⛓	Workers persistentes	Um supervisor posterior pode descobrir e adotar um worker existente para o mesmo banco de dados.
◎	Fluxo de trabalho em lote	Aqueça a análise e os caches de construção para uma coleção de amostras com uma única chamada `idb_batch_open`.
⛨	Superfície controlada	Perfis somente leitura, ferramentas inseguras opt-in, limites de workers, timeouts e limpeza ociosa mantêm a automação limitada.

O cache fica ao lado do IDB como <database>.mcp.sqlite. A atualização é verificada em relação ao horário de modificação do IDB e ao esquema do cache, para que linhas obsoletas não sejam reutilizadas silenciosamente.

Início rápido

1. Pré-requisitos

IDA Pro 8.3 ou mais recente; IDA 9.x é recomendado
Python 3.11 ou mais recente
uv / uvx
Qualquer cliente MCP que possa iniciar um servidor stdio local

Instale o uv se não estiver disponível:

python -m pip install uv

Ative o ambiente Python headless do IDA uma vez:

# Windows — adjust the IDA version/path if needed
uv run "C:\Program Files\IDA Professional 9.3\idalib\python\py-activate-idalib.py"

# macOS — adjust the IDA version/path if needed
uv run "/Applications/IDA Professional 9.3.app/Contents/MacOS/idalib/python/py-activate-idalib.py"

2. Adicione o servidor MCP

A configuração recomendada executa o código mais recente diretamente deste repositório:

{
  "mcpServers": {
    "ida-pro-mcp-fusion": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/rison1337/ida-pro-mcp-fusion",
        "idalib-mcp",
        "--stdio"
      ]
    }
  }
}

Claude Code:

claude mcp add ida-pro-mcp-fusion -- uvx --from git+https://github.com/rison1337/ida-pro-mcp-fusion idalib-mcp --stdio

Ou baixe o pacote MCP empacotado da última versão.

3. Abra um banco de dados

Peça ao agente conectado para começar com:

idb_open(
    "C:/samples/target.exe",
    preferred_session_id="target",
    build_caches=True,
    init_hexrays=True,
)

Cada chamada de análise então nomeia seu banco de dados explicitamente:

survey_binary(database="target")
decompile("main", database="target")
xrefs_to("WinMain", database="target")
cache_callgraph_hotspots(limit=25, database="target")

Arquitetura

Seu cliente MCP inicia o idalib-mcp via stdio ou HTTP.
O supervisor cria ou adota um worker por binário e aplica o limite de workers.
As chamadas de ferramenta incluem um ID de sessão database, para que as solicitações sejam roteadas para o IDB correto.
O IDA realiza descompilação ao vivo e trabalho de mutação; as ferramentas de cache servem consultas indexadas do banco de dados SQLite auxiliar.
Os workers permanecem detectáveis no host e se limpam após seu TTL ocioso.

Bancos de dados GUI também podem participar. O idb_open suporta quatro modos de roteamento:

Modo	Comportamento
`prefer_headless`	Usar ou criar um worker idalib. Este é o padrão.
`force_headless`	Nunca adotar uma instância GUI em execução.
`prefer_gui`	Adotar uma instância GUI correspondente, caso contrário criar um worker.
`force_gui`	Adotar uma instância GUI correspondente ou iniciar o IDA GUI.

Fluxo de trabalho multi-binário

Abra uma pequena coleção e mantenha cada sessão disponível:

idb_batch_open(
    [
        "C:/samples/loader.exe",
        "C:/samples/payload.dll",
        "C:/samples/helper.dll",
    ],
    session_prefix="case42",
    refresh_cache=True,
    cache_include_xrefs=True,
)

Para um corpus grande, construa cada cache e libere seu worker imediatamente:

idb_batch_open(
    ["C:/corpus/a.exe", "C:/corpus/b.exe", "C:/corpus/c.exe"],
    close_after_cache=True,
    retry_without_auto_analysis_on_timeout=True,
)

Controles de sessão úteis:

idb_list()
idb_close(database="case42_1_loader")

Superfície de ferramentas

O código registra 75 ferramentas de análise voltadas ao IDA, além dos controles multi-sessão do supervisor. O número exato visível a um cliente varia intencionalmente: ferramentas de depurador são uma extensão, operações perigosas são desabilitadas a menos que explicitamente habilitadas, e um perfil pode expor uma allowlist menor.

Área	Ferramentas representativas
Sessões	`idb_open`, `idb_batch_open`, `idb_list`, `idb_close`, `idb_save`
Levantamento e descompilação	`survey_binary`, `decompile`, `disasm`, `analyze_function`, `analyze_component`
Busca e relacionamentos	`find`, `find_bytes`, `search_text`, `xrefs_to`, `callees`, `callgraph`, `trace_data_flow`
Cache persistente	`cache_status`, `refresh_cache`, `cache_entity_query`, `cache_xrefs`, `cache_callgraph_hotspots`, `cache_find_regex`
Tipos e pilha	`declare_type`, `type_inspect`, `set_type`, `infer_types`, `stack_frame`, `declare_stack`
Edição de banco de dados	`rename`, `set_comments`, `define_func`, `define_code`, `patch_asm`, `make_data`
Assinaturas	`make_signature`, `make_signature_for_function`, `make_signature_for_range`, `find_xref_signatures`
Extensão do depurador	`dbg_start`, `dbg_bps`, `dbg_regs`, `dbg_stacktrace`, `dbg_read`, `dbg_write`

As nove ferramentas específicas de cache são:

cache_status              refresh_cache
cache_refresh_if_stale    cache_list_funcs
cache_entity_query        cache_xrefs
cache_callgraph           cache_callgraph_hotspots
cache_find_regex

Configuração

Pool de workers

uvx --from git+https://github.com/rison1337/ida-pro-mcp-fusion \
  idalib-mcp --stdio --max-workers 4

Opção / variável	Finalidade
`--max-workers N`	Máximo de workers de banco de dados simultâneos; `0` significa ilimitado. Padrão: `4`.
`IDA_MCP_MAX_WORKERS`	Padrão de ambiente para o limite de workers.
`IDA_MCP_OPEN_TIMEOUT`	Tempo máximo de abertura com auto-análise em segundos. Padrão: `1800`; `0` desabilita o limite.
`IDA_MCP_LOAD_TIMEOUT`	Tempo máximo de abertura somente carregamento em segundos. Padrão: `300`; `0` desabilita o limite.

Perfis restritos

Exponha apenas um conjunto selecionado de ferramentas:

idalib-mcp --stdio --profile profiles/readonly.txt

Dois perfis prontos para uso estão incluídos:

profiles/readonly.txt — inspeção sem ferramentas de mutação
profiles/triage.txt — superfície compacta de análise de primeira passagem

As ferramentas de gerenciamento permanecem disponíveis para que as sessões ainda possam ser abertas e inspecionadas.

Transporte HTTP

idalib-mcp --host 127.0.0.1 --port 8745

Ponte GUI do IDA:

ida-pro-mcp --transport http://127.0.0.1:8744/sse

Para instalar o plugin GUI e gerar a configuração do cliente interativamente:

python -m pip install https://github.com/rison1337/ida-pro-mcp-fusion/archive/refs/heads/main.zip
ida-pro-mcp --install

Reinicie o IDA e o cliente MCP após a instalação.

Notas de segurança

O servidor vincula-se ao loopback por padrão. Não o exponha a uma rede não confiável.
Ferramentas de mutação e Python arbitrário são marcadas como inseguras e não são habilitadas por padrão.
py_eval, py_exec_file, controles do depurador e operações de patch podem executar código ou alterar permanentemente um IDB. Habilite-os apenas para clientes e entradas confiáveis.
Analise binários não confiáveis dentro do mesmo limite de isolamento que você usaria para análise manual de malware.

Habilite ferramentas de worker inseguras somente quando o fluxo de trabalho exigir:

idalib-mcp --stdio --unsafe

Solução de problemas

uvx não é reconhecido

Instale o uv com python -m pip install uv, abra um novo terminal e confirme com uvx --version.

Incompatibilidade de versão Python / IDA

Execute o Hex-Rays idapyswitch, selecione uma instalação Python 3.11+ e ative o idalib novamente com py-activate-idalib.py.

Uma chamada de banco de dados diz que database é obrigatório

Chame idb_list() e passe o session_id retornado como database=. Caminhos e nomes de arquivo não são aceitos no lugar de um ID de sessão.

O limite de workers foi atingido

Feche uma sessão não utilizada com idb_close, aumente --max-workers ou use close_after_cache=True para indexação de corpus.

Desenvolvimento

Clone o repositório e execute a suíte de testes independente de plataforma:

git clone https://github.com/rison1337/ida-pro-mcp-fusion.git
cd ida-pro-mcp-fusion
python -m pip install pytest jsonschema "mcp>=1.0" "tomli-w>=1.0"
python -m pytest -q tests

Execute a suíte com suporte ao IDA em um ambiente IDA ativado:

uv run ida-mcp-test tests/typed_fixture.elf -q

Novas ferramentas IDA ficam em src/ida_pro_mcp/ida_mcp/api_*.py e são registradas por meio do decorador @tool. Testes de ciclo de vida de supervisor e worker ficam em tests/.

Identidade do projeto e créditos

A Fusion Edition é mantida por rison1337.

O projeto baseia-se no código-fonte mrexodia/ida-pro-mcp licenciado sob MIT. Seu cache persistente e orquestração headless também incorporam ideias desenvolvidas em QiuChenly/ida-pro-mcp-enhancement e winmin/ida-headless-mcp. A atribuição é mantida aqui e no histórico do código-fonte; o empacotamento, as ferramentas de cache, o fluxo de trabalho em lote, o ciclo de vida de sessão e a identidade pública do Fusion são mantidos neste repositório.

Licença

Distribuído sob a Licença MIT. IDA Pro e Hex-Rays são marcas registradas da Hex-Rays SA e não estão incluídos neste projeto.

Русский

Одна MCP-точка. Много бинарников. Контекст анализа сохраняется.

Быстрый старт · Почему Fusion · Архитектура · Инструменты · Настройка

Что такое Fusion?

IDA Pro MCP Fusion подключает MCP-совместимых агентов к IDA Pro и превращает одно соединение в полноценное рабочее место для реверсинга. Живой анализ IDA объединён с постоянным SQLite-индексом и supervisor-процессом, который может держать несколько бинарников в изолированных headless-воркерах.

Можно декомпилировать и дизассемблировать функции, исследовать перекрёстные ссылки, типы и граф вызовов, переименовывать символы, патчить данные, создавать сигнатуры и повторно использовать уже построенный анализ.

[!IMPORTANT] Нужна локальная лицензированная установка IDA Pro. IDA Free не поддерживается. Сервер не содержит IDA, Hex-Rays и не отправляет бинарники во внешний сервис.

Почему Fusion

	Возможность	Что это даёт
⚡	Постоянный SQLite-кэш	Функции, строки, глобальные переменные, импорты, xref и call graph доступны между запусками.
◈	Мульти-бинарный supervisor	Несколько GUI- или headless-баз управляются через одну MCP-точку.
⛓	Живущие воркеры	Следующее подключение может найти и принять уже запущенный worker для той же базы.
◎	Пакетный анализ	Открытие образцов и построение кэшей выполняется одним `idb_batch_open`.
⛨	Контролируемый интерфейс	Read-only-профили, лимит воркеров, тайм-ауты и opt-in для опасных инструментов.
O cache fica ao lado do IDB no arquivo `<database>.mcp.sqlite`. A atualidade é verificada pela hora de modificação do IDB e pela versão do esquema, portanto dados desatualizados não são fornecidos silenciosamente.

Início rápido

1. O que você vai precisar

IDA Pro 8.3 ou mais recente; recomenda-se IDA 9.x
Python 3.11 ou mais recente
uv / uvx
Um cliente MCP que saiba executar um servidor stdio local

Instale o uv, se ainda não o tiver:

python -m pip install uv

Ative o Python headless do IDA uma vez:

# Windows — при необходимости измените версию и путь к IDA
uv run "C:\Program Files\IDA Professional 9.3\idalib\python\py-activate-idalib.py"

# macOS — при необходимости измените версию и путь к IDA
uv run "/Applications/IDA Professional 9.3.app/Contents/MacOS/idalib/python/py-activate-idalib.py"

2. Adicione o servidor MCP

A configuração recomendada executa o código diretamente deste repositório:

{
  "mcpServers": {
    "ida-pro-mcp-fusion": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/rison1337/ida-pro-mcp-fusion",
        "idalib-mcp",
        "--stdio"
      ]
    }
  }
}

Para Claude Code:

claude mcp add ida-pro-mcp-fusion -- uvx --from git+https://github.com/rison1337/ida-pro-mcp-fusion idalib-mcp --stdio

Um pacote MCPB pronto está disponível na última versão.

3. Abra o banco de dados

Peça ao agente conectado para começar assim:

idb_open(
    "C:/samples/target.exe",
    preferred_session_id="target",
    build_caches=True,
    init_hexrays=True,
)

Cada chamada de análise subsequente recebe um ID de banco explícito:

survey_binary(database="target")
decompile("main", database="target")
xrefs_to("WinMain", database="target")
cache_callgraph_hotspots(limit=25, database="target")

Arquitetura

O cliente MCP inicia o idalib-mcp via stdio ou HTTP.
O supervisor cria ou aceita um processo worker por binário.
Cada chamada contém o database, então a solicitação chega à sessão IDB correta.
O IDA executa análise e modificações ao vivo, e as ferramentas de cache leem o índice do SQLite.
Os workers permanecem detectáveis no computador e são encerrados após um período de inatividade.

O idb_open suporta quatro modos:

Modo	Comportamento
`prefer_headless`	Usar ou criar um idalib-worker. Modo padrão.
`force_headless`	Não aceitar um processo GUI em execução.
`prefer_gui`	Aceitar um GUI adequado e, se não houver, criar um worker.
`force_gui`	Aceitar um GUI ou iniciar um novo processo IDA.

Trabalhando com vários binários

Abra várias amostras e mantenha todas as sessões disponíveis:

idb_batch_open(
    [
        "C:/samples/loader.exe",
        "C:/samples/payload.dll",
        "C:/samples/helper.dll",
    ],
    session_prefix="case42",
    refresh_cache=True,
    cache_include_xrefs=True,
)

Para um corpus grande, você pode construir o cache e liberar o worker imediatamente:

idb_batch_open(
    ["C:/corpus/a.exe", "C:/corpus/b.exe", "C:/corpus/c.exe"],
    close_after_cache=True,
    retry_without_auto_analysis_on_timeout=True,
)

Gerenciamento de sessões:

idb_list()
idb_close(database="case42_1_loader")

Ferramentas

Na base de código estão registradas 75 ferramentas de análise do IDA, e o supervisor adiciona o gerenciamento de sessões multi-binário. A lista visível ao cliente muda intencionalmente: as ferramentas de debugger são uma extensão, operações perigosas ficam desativadas sem permissão explícita, e o perfil pode manter apenas os nomes selecionados.

Área	Exemplos
Sessões	`idb_open`, `idb_batch_open`, `idb_list`, `idb_close`, `idb_save`
Visão geral e descompilação	`survey_binary`, `decompile`, `disasm`, `analyze_function`, `analyze_component`
Busca e referências	`find`, `find_bytes`, `search_text`, `xrefs_to`, `callees`, `callgraph`, `trace_data_flow`
Cache persistente	`cache_status`, `refresh_cache`, `cache_entity_query`, `cache_xrefs`, `cache_callgraph_hotspots`, `cache_find_regex`
Tipos e pilha	`declare_type`, `type_inspect`, `set_type`, `infer_types`, `stack_frame`, `declare_stack`
Modificação do banco	`rename`, `set_comments`, `define_func`, `define_code`, `patch_asm`, `make_data`
Assinaturas	`make_signature`, `make_signature_for_function`, `make_signature_for_range`, `find_xref_signatures`
Extensão de debugger	`dbg_start`, `dbg_bps`, `dbg_regs`, `dbg_stacktrace`, `dbg_read`, `dbg_write`

Configuração

Pool de workers

uvx --from git+https://github.com/rison1337/ida-pro-mcp-fusion \
  idalib-mcp --stdio --max-workers 4

Parâmetro / variável	Finalidade
`--max-workers N`	Máximo de bancos trabalhando simultaneamente; `0` — sem limite. Padrão: `4`.
`IDA_MCP_MAX_WORKERS`	Valor de limite padrão do ambiente.
`IDA_MCP_OPEN_TIMEOUT`	Tempo máximo de autoanálise ao abrir, em segundos. Padrão: `1800`.
`IDA_MCP_LOAD_TIMEOUT`	Tempo máximo de carregamento sem autoanálise. Padrão: `300`.

Perfis restritos

Manter apenas as ferramentas selecionadas:

idalib-mcp --stdio --profile profiles/readonly.txt

profiles/readonly.txt — visualização sem ferramentas de modificação
profiles/triage.txt — conjunto compacto para análise inicial

HTTP

idalib-mcp --host 127.0.0.1 --port 8745

Ponte GUI:

ida-pro-mcp --transport http://127.0.0.1:8744/sse

Para instalar o plugin GUI:

python -m pip install https://github.com/rison1337/ida-pro-mcp-fusion/archive/refs/heads/main.zip
ida-pro-mcp --install

Após a instalação, reinicie o IDA e o cliente MCP.

Segurança

Por padrão, o servidor escuta apenas em loopback. Não o exponha a uma rede não confiável.
Ferramentas de modificação e de Python arbitrário são marcadas como unsafe e desativadas por padrão.
py_eval, py_exec_file, comandos de debugger e patches podem executar código ou alterar o IDB.
Analise binários não verificados no mesmo isolamento que na análise manual de malware.

Você pode ativar as ferramentas unsafe explicitamente:

idalib-mcp --stdio --unsafe

Solução de problemas

uvx não encontrado

Instale o uv com o comando python -m pip install uv, abra um novo terminal e verifique o uvx --version.

Versão incompatível de Python ou IDA

Execute o idapyswitch, selecione Python 3.11+ e depois execute novamente o py-activate-idalib.py.

Erro informando que é necessário um database

Chame o idb_list() e passe o session_id retornado como database=. Caminhos e nomes de arquivo não são aceitos no lugar do ID da sessão.

Limite de workers atingido

Feche a sessão não utilizada via idb_close, aumente o --max-workers ou use o close_after_cache=True.

Desenvolvimento

git clone https://github.com/rison1337/ida-pro-mcp-fusion.git
cd ida-pro-mcp-fusion
python -m pip install pytest jsonschema "mcp>=1.0" "tomli-w>=1.0"
python -m pytest -q tests

Para testes que precisam do próprio IDA:

uv run ida-mcp-test tests/typed_fixture.elf -q

As novas ferramentas ficam em src/ida_pro_mcp/ida_mcp/api_*.py e são registradas via @tool. Os testes de supervisor e lifecycle estão em tests/.

Projeto e autoria

Fusion Edition é mantida por rison1337.

O projeto é baseado na base de código MIT de mrexodia/ida-pro-mcp. O cache persistente e a orquestração headless também usam ideias de QiuChenly/ida-pro-mcp-enhancement e winmin/ida-headless-mcp. A atribuição é mantida no README e no histórico das fontes; o empacotamento Fusion, as ferramentas de cache, o batch workflow e o lifecycle das sessões são mantidos neste repositório.

Licença

O projeto é distribuído sob a MIT License. IDA Pro e Hex-Rays são marcas registradas da Hex-Rays SA e não fazem parte do projeto.