themixednuts/ghidramcp/ghidra-mcp

Ghidra MCP Skill

This skill enables reverse engineering workflows using Ghidra through the Model Context Protocol (MCP).

Quick Start

1. List available programs: read the ghidra://programs resource
2. Read functions: use functions with action: "list" and filters to find targets
3. Decompile: use inspect with action: "decompile" for C-like output
4. Analyze references: use inspect with action: "references_to" or "references_from"

Core Workflows

Analyzing a New Binary

1. Read ghidra://programs to confirm the binary is loaded
2. Use functions with action: "list" to get compact function rows
3. Use inspect with action: "decompile" on interesting functions

• For a known token in a large function, pass search_text and follow

next_match_offset. Omit search_text and use start_line to read a source window. Pass the returned decompilation_id on either follow-up path to reuse the completed result.

• When the function is unknown, use inspect with action: "search_code" and

search_text. Follow next_cursor until complete is true.

1. Use inspect reference actions to understand how functions/data are used
2. Use symbols / functions update actions to rename symbols and variables

Understanding a Function

1. functions with action: "get" and name, address, or symbol_id
2. inspect with action: "decompile" to see decompiled C code
3. functions with action: "list_variables" to see stable variable targets
4. analyze with action: "graph" to see control flow
5. inspect with action: "references_to" to find callers

Defining Data Structures

1. data_types with action: "list" to check existing types
2. data_types with action: "create" and data_type_kind: "struct" to create structures
3. Add fields with proper offsets and types
4. Use data_types with action: "update" to modify existing types
5. Use memory with action: "map_data_type" to apply the type at an address and inspect the bounded byte-to-field mapping

Searching for Patterns

1. memory with action: "search" and search_type: "string" for string literals
2. memory with action: "search" and search_type: "hex" for byte patterns
3. memory with action: "search" and search_type: "regex" for complex patterns
4. Follow up with inspect reference actions on interesting addresses

MCP Result Handling

When a programmable MCP host hands a tool result to the model, pass {isError, result: structuredContent ?? content}. Keep the full tool result for the host UI or logs. This selects one response representation for model context while the server retains the text fallback for compatible MCP clients.

For Codex functions.exec, project the nested MCP result before emitting it:

const result = await tools.mcp__ghidra__inspect(args);
text({ isError: result.isError === true, result: result.structuredContent ?? result.content });

Bulk Operations

Use batch_operations to execute multiple changes atomically:

• Rename multiple symbols
• Create multiple data types
• All operations succeed or all are rolled back

Tool Categories

Read Operations (No Modifications)

Write Operations (Modify Program)

Delete Operations

Utility Operations

Debugger Control

Use debugger for the full Ghidra debugger lifecycle. Start with {"action": "status"} and {"action": "list_connections"} to see whether a trace/target is already active. If not, use list_launchers with file_name, then launch with the selected launcher_index or launcher_name.

After launch or attach, use list_traces, list_targets, activate_trace, activate_target, list_threads, list_stack, list_snapshots, and list_objects to discover the trace model, then activate_thread, activate_frame, activate_snap, activate_time, or activate_object to select the active debugger context. Use list_modules, list_sections, or list_memory_regions followed by apply_mapping with mapping_kind: "module", "section", or "region" and file_name to map the running target back to the static analyzed Program.

Prefer structured actions such as resume, interrupt, step_over, detach, kill, read_memory, write_memory, set_breakpoint, set_watchpoint, read_registers, list_watches, and map_data_type; use execute for raw debugger-console commands. Use list_remote_methods and invoke_remote_method when the Trace RMI backend exposes a capability that does not yet have a structured action.

Use read_memory for live target bytes; it refreshes the trace from the target by default when a live target is selected. Use read_trace_bytes and write_trace_bytes only when you intentionally want cached trace bytes without touching the target. Use get_memory_state/set_memory_state to reason about known, unknown, or error byte state.

debugger.map_data_type applies a data type in the current trace view and returns a bounded byte-to-field mapping. list_registers, read_registers, and list_watches use max_registers/max_watches plus next_cursor pagination. Broad debugger discovery actions use page_size plus next_cursor.

Common Patterns

Pagination

Most broad read operations are intentionally bounded. Start with an explicit limit such as page_size, max_lines, or max_results, then pass the response next_cursor back as cursor to get the next page. Keep the same filters and target arguments while paging.

{"action": "list", "page_size": 50, "cursor": "returned_next_cursor_value"}

UI Synchronization

Focused CodeBrowser operations also update the user's active Ghidra UI when the server is running inside a tool with navigation services. inspect.decompile, inspect.listing, functions.get, functions.create, functions.update_prototype, memory.define, memory.map_data_type, project.go_to_address, and focused debugger actions navigate to the resolved function or address automatically; the structured response payload stays unchanged.

Identifying Targets

Tools accept multiple ways to identify targets:

• By address: "address": "0x401000"
• By name: "name": "main"
• By ID: "symbol_id": 12345 or "variable_symbol_id": "12345"

Address Formats

Addresses can be specified as:

• Hex with prefix: "0x401000"
• Hex without prefix: "401000"
• Image-base-relative offset: "+0x401000" or "+401000"
• Module-prefixed image-base-relative offset: "NewWorld+0x401000"

Tips

1. Start broad, then narrow: Use list operations first, then read specific items
2. Use filtering: Most list operations support name_pattern regex filters
3. Check before modifying: Read the current state before making changes
4. Use batch for related changes: Group related modifications in batch_operations
5. Undo mistakes: Use project with action: "undo" if something goes wrong

Reference

See references/TOOLS.md for detailed documentation of each tool's operations and parameters.