MCP Tools

MCGhidra exposes Ghidra’s capabilities as MCP tools. There are 64 tools across 14 categories.

Pagination Convention

Most list tools share a common set of pagination and filtering parameters. Rather than repeating them in every table, they are documented once here:

Parameter	Type	Default	Description
port	int	current	Ghidra instance port. Uses the active instance if omitted.
page_size	int	50	Items per page. Maximum: 500.
grep	string	none	Client-side regex pattern applied to results after fetching.
grep_ignorecase	bool	true	Case-insensitive grep matching.
return_all	bool	false	Bypass pagination and return everything. Triggers a budget guard if the response exceeds ~8000 tokens.
fields	list[str]	none	Field projection — keep only these keys per item. Reduces response size.

Tools that accept these parameters are marked with “Supports pagination” below. Use cursor_next(cursor_id) to advance through pages.

---

Instance Management

Tools for discovering, registering, and switching between Ghidra instances.

instances_list

List all active Ghidra instances. Runs a quick discovery scan before returning results.

Returns a dict with an instances list containing port, URL, project, and file for each instance.

instances_use

Set the current working instance. All subsequent tool calls default to this instance.

Uses lazy registration — the instance is recorded immediately without a blocking HTTP call. If the instance is unreachable, the next actual tool call will fail with a clear error.

Parameter	Type	Default	Description
port	int	required	Port number of the instance to activate

Returns confirmation with instance details.

instances_current

Show which instance is currently active, including its port, URL, project, and file. Returns an error message with available instance ports if none is set.

instances_register

Manually register an instance by port. Verifies the instance is responsive and checks API version compatibility before registering.

Parameter	Type	Default	Description
port	int	required	Port number
url	string	auto	URL override (defaults to http://{GHIDRA_HOST}:{port})

Returns confirmation or error message.

instances_unregister

Remove an instance from the registry. If the unregistered instance was the current working instance, the current selection is cleared.

Parameter	Type	Default	Description
port	int	required	Port number to unregister

instances_discover

Force a full discovery scan across the configured port range (ports 18400-18600). Use this when you need to find instances on a different host. For normal use, instances_list already runs a quick scan.

Parameter	Type	Default	Description
host	string	configured	Host to scan

program_info

Get full program metadata from the current Ghidra instance: architecture, language ID, compiler spec, image base address, and total memory size.

Parameter	Type	Default	Description
port	int	current	Ghidra instance port

---

Functions

Tools for listing, decompiling, disassembling, and modifying functions. Supports pagination.

functions_list

List functions with cursor-based pagination and server-side filtering. For large binaries, use name_contains or name_regex for server-side filtering before results reach the client.

Parameter	Type	Default	Description
name_contains	string	none	Server-side substring filter (faster than grep for large binaries)
name_regex	string	none	Server-side regex filter on function name
address	string	none	Filter by exact function address (hex)

Supports pagination.

functions_get

Get detailed information about a single function: name, address, signature, size, stack depth, calling convention.

Parameter	Type	Default	Description
name	string	none	Function name (mutually exclusive with address)
address	string	none	Function address in hex
port	int	current	Ghidra instance port

functions_decompile

Decompile a function to C pseudocode. Output is split into lines for pagination — use grep to search within the decompiled code.

Parameter	Type	Default	Description
name	string	none	Function name (mutually exclusive with address)
address	string	none	Function address in hex
syntax_tree	bool	false	Include the decompiler syntax tree (JSON)
style	string	"normalize"	Decompiler simplification style

Supports pagination (over decompiled lines).

functions_disassemble

Get assembly-level disassembly for a function. Output is split into instruction lines for pagination.

Parameter	Type	Default	Description
name	string	none	Function name (mutually exclusive with address)
address	string	none	Function address in hex

Supports pagination (over instruction lines).

functions_rename

Rename a function. Identify it by current name or address.

Parameter	Type	Default	Description
old_name	string	none	Current function name
address	string	none	Function address in hex
new_name	string	required	New name for the function
port	int	current	Ghidra instance port

functions_set_signature

Set the full prototype of a function, including return type, name, and parameter types.

Parameter	Type	Default	Description
name	string	none	Function name
address	string	none	Function address in hex
signature	string	required	Full signature (e.g., "int foo(char* arg1, int arg2)")
port	int	current	Ghidra instance port

functions_set_comment

Set a decompiler-level comment on a function. Tries the function comment first, then falls back to a pre-comment if the address is not a function entry point.

Parameter	Type	Default	Description
address	string	required	Memory address (preferably function entry point)
comment	string	""	Comment text. Empty string removes the comment.
port	int	current	Ghidra instance port

functions_create

Create a new function definition at the specified address. Ghidra will attempt to determine the function boundaries automatically.

Parameter	Type	Default	Description
address	string	required	Memory address in hex
port	int	current	Ghidra instance port

functions_variables

List local variables and parameters for a specific function. Supports pagination.

Parameter	Type	Default	Description
address	string	required	Function address in hex

Supports pagination.

---

Data

Tools for working with defined data items and strings.

data_list

List defined data items with filtering and cursor-based pagination.

Parameter	Type	Default	Description
addr	string	none	Filter by address (hex)
name	string	none	Exact name match (case-sensitive)
name_contains	string	none	Substring name filter (case-insensitive)
type	string	none	Filter by data type (e.g., "string", "dword")

Supports pagination.

data_list_strings

List all defined strings in the binary. Use filter for server-side content matching, or grep for client-side regex.

Parameter	Type	Default	Description
filter	string	none	Server-side string content filter

Supports pagination.

data_create

Define a new data item at the specified address.

Parameter	Type	Default	Description
address	string	required	Memory address in hex
data_type	string	required	Data type (e.g., "string", "dword", "byte")
size	int	none	Size in bytes (optional)
port	int	current	Ghidra instance port

data_rename

Rename a data item at the specified address.

Parameter	Type	Default	Description
address	string	required	Memory address in hex
name	string	required	New name
port	int	current	Ghidra instance port

data_set_type

Change the data type of an existing data item.

Parameter	Type	Default	Description
address	string	required	Memory address in hex
data_type	string	required	New data type (e.g., "uint32_t", "char[10]")
port	int	current	Ghidra instance port

data_delete

Remove a data definition at the specified address.

Parameter	Type	Default	Description
address	string	required	Memory address in hex
port	int	current	Ghidra instance port

---

Structs

Tools for creating and modifying struct (composite) data types.

structs_list

List all struct data types. Supports pagination.

Parameter	Type	Default	Description
category	string	none	Filter by category path (e.g., "/winapi")

Supports pagination.

structs_get

Get a struct with all its fields. If the struct has more than 10 fields, the field list is paginated. Use fields projection to reduce response size.

Parameter	Type	Default	Description
name	string	required	Struct name

Supports pagination (over struct fields).

structs_create

Create a new struct data type.

Parameter	Type	Default	Description
name	string	required	Name for the struct
category	string	none	Category path (e.g., "/custom")
description	string	none	Description text
port	int	current	Ghidra instance port

structs_add_field

Add a field to an existing struct. If offset is omitted, the field is appended to the end of the struct.

Parameter	Type	Default	Description
struct_name	string	required	Name of the struct
field_name	string	required	Name for the new field
field_type	string	required	Data type (e.g., "int", "char", "pointer")
offset	int	none	Byte offset within the struct
comment	string	none	Field comment
port	int	current	Ghidra instance port

structs_update_field

Modify an existing field in a struct. Identify the field by name or offset. At least one of new_name, new_type, or new_comment must be provided.

Parameter	Type	Default	Description
struct_name	string	required	Name of the struct
field_name	string	none	Current field name (or use field_offset)
field_offset	int	none	Field offset (or use field_name)
new_name	string	none	New name
new_type	string	none	New data type
new_comment	string	none	New comment
port	int	current	Ghidra instance port

structs_delete

Remove a struct data type definition.

Parameter	Type	Default	Description
name	string	required	Struct name to delete
port	int	current	Ghidra instance port

---

Symbols

Tools for working with the symbol table: labels, imports, and exports.

symbols_list

List all symbols in the program. Supports pagination.

Supports pagination.

symbols_create

Create a new label/symbol at the specified address. If a symbol already exists at that address, it is renamed.

Parameter	Type	Default	Description
name	string	required	Symbol name
address	string	required	Memory address in hex
port	int	current	Ghidra instance port

symbols_rename

Rename the primary symbol at an address.

Parameter	Type	Default	Description
address	string	required	Memory address in hex
new_name	string	required	New name
port	int	current	Ghidra instance port

symbols_delete

Delete the primary symbol at an address.

Parameter	Type	Default	Description
address	string	required	Memory address in hex
port	int	current	Ghidra instance port

symbols_imports

List imported symbols (external references). Supports pagination.

Supports pagination.

symbols_exports

List exported symbols (entry points). Supports pagination.

Supports pagination.

---

Analysis

Tools for triggering and inspecting Ghidra analysis results.

analysis_run

Trigger Ghidra’s auto-analysis on the current program.

Parameter	Type	Default	Description
port	int	current	Ghidra instance port
analysis_options	dict	none	Analysis options to enable/disable

analysis_get_callgraph

Generate a call graph starting from a function. Returns nodes and edges. Edges are paginated.

Parameter	Type	Default	Description
name	string	none	Starting function name
address	string	none	Starting function address
max_depth	int	3	Maximum call depth

Supports pagination (over edges).

analysis_get_dataflow

Trace data flow forward or backward from an address. Returns a list of steps showing how data propagates through the program.

Parameter	Type	Default	Description
address	string	required	Starting address in hex
direction	string	"forward"	"forward" or "backward"
max_steps	int	50	Maximum analysis steps

Supports pagination (over steps).

xrefs_list

Find cross-references to or from an address. At least one of to_addr or from_addr is required.

Parameter	Type	Default	Description
to_addr	string	none	Find references to this address
from_addr	string	none	Find references from this address
type	string	none	Filter by type: "CALL", "READ", "WRITE", "DATA", "POINTER"

Supports pagination.

comments_get

Get a comment at the specified address.

Parameter	Type	Default	Description
address	string	required	Memory address in hex
comment_type	string	"plate"	Type: "plate", "pre", "post", "eol", "repeatable"
port	int	current	Ghidra instance port

comments_set

Set a comment at the specified address. Pass an empty string to remove the comment.

Parameter	Type	Default	Description
address	string	required	Memory address in hex
comment	string	""	Comment text
comment_type	string	"plate"	Type: "plate", "pre", "post", "eol", "repeatable"
port	int	current	Ghidra instance port

---

Memory

Direct memory access tools.

memory_read

Read bytes from a memory address.

Parameter	Type	Default	Description
address	string	required	Memory address in hex
length	int	16	Number of bytes to read
format	string	"hex"	Output format: "hex", "base64", or "string"
port	int	current	Ghidra instance port

Returns the bytes in the requested format along with the actual byte count.

memory_write

Write bytes to a memory address. Use with caution — this modifies the program state.

Parameter	Type	Default	Description
address	string	required	Memory address in hex
bytes_data	string	required	Data to write
format	string	"hex"	Input format: "hex", "base64", or "string"
port	int	current	Ghidra instance port

---

Variables

Tools for querying and renaming variables.

variables_list

List variables with optional global-only filtering. Supports pagination.

Parameter	Type	Default	Description
global_only	bool	false	Return only global variables

Supports pagination.

variables_rename

Rename a variable within a function, and optionally change its data type.

Parameter	Type	Default	Description
function_address	string	required	Function address in hex
variable_name	string	required	Current variable name
new_name	string	required	New name
new_type	string	none	New data type (e.g., "int", "char*")
port	int	current	Ghidra instance port

---

Bookmarks

Tools for managing Ghidra bookmarks (annotations at addresses).

bookmarks_list

List bookmarks with optional type and category filtering. Supports pagination.

Parameter	Type	Default	Description
type	string	none	Filter by type: "Note", "Warning", "Error", "Info"
category	string	none	Filter by category

Supports pagination.

bookmarks_create

Create a bookmark at the specified address.

Parameter	Type	Default	Description
address	string	required	Memory address in hex
type	string	"Note"	Bookmark type: Note, Warning, Error, Info
category	string	""	Category string for grouping
comment	string	""	Bookmark comment text
port	int	current	Ghidra instance port

bookmarks_delete

Delete all bookmarks at the specified address.

Parameter	Type	Default	Description
address	string	required	Memory address in hex
port	int	current	Ghidra instance port

---

Enums and Typedefs

Tools for managing enum and typedef data types.

enums_list

List enum data types with their members. Supports pagination.

Supports pagination.

enums_create

Create a new enum data type.

Parameter	Type	Default	Description
name	string	required	Enum name
size	int	4	Size in bytes
port	int	current	Ghidra instance port

typedefs_list

List typedef data types. Supports pagination.

Supports pagination.

typedefs_create

Create a new typedef data type.

Parameter	Type	Default	Description
name	string	required	Typedef name
base_type	string	required	Base data type (e.g., "int", "uint32_t", "char*")
port	int	current	Ghidra instance port

---

Namespaces

Tools for querying namespaces and class definitions.

namespaces_list

List all non-global namespaces in the program. Supports pagination.

Supports pagination.

classes_list

List class namespaces with qualified names. Supports pagination.

Supports pagination.

---

Segments

segments_list

List memory segments (.text, .data, .bss, etc.) with read/write/execute permissions, start address, and size.

Parameter	Type	Default	Description
name	string	none	Filter by segment name (exact match)

Supports pagination.

---

Cursors

Tools for managing pagination state. Every paginated tool response includes a cursor_id in the pagination metadata when more pages are available.

cursor_next

Fetch the next page of results for a cursor. Cursors expire after 5 minutes of inactivity.

Parameter	Type	Default	Description
cursor_id	string	required	Cursor identifier from a previous paginated response

Returns the next page of results with updated pagination info.

cursor_list

List active cursors for the current session.

Parameter	Type	Default	Description
all_sessions	bool	false	Include cursors from all sessions

cursor_delete

Delete a specific cursor to free resources.

Parameter	Type	Default	Description
cursor_id	string	required	Cursor identifier to delete

cursor_delete_all

Delete all cursors for the current session.

---

Docker

Tools for managing Ghidra Docker containers. See the Docker Usage page for environment variables and firmware import details.

docker_auto_start

The primary entry point for automatic container management. Checks all pooled ports for an existing instance analyzing the same binary. If none is found, allocates a port and starts a new container. Returns connection info immediately — poll docker_health to check when the API is ready.

Parameter	Type	Default	Description
binary_path	string	required	Path to the binary file
language	string	none	Ghidra processor language ID (e.g., "ARM:LE:32:v4t")
base_address	string	none	Base address for raw binaries (e.g., "0x00000000")
loader	string	none	Loader type. Auto-set to "BinaryLoader" when language is specified.

docker_start

Start a container with explicit control over all parameters. Ports are auto-allocated from the pool (8192-8319).

Parameter	Type	Default	Description
binary_path	string	required	Path to the binary file
memory	string	"2G"	Max JVM heap size
name	string	auto	Container name (auto-generated with session ID)
language	string	none	Ghidra processor language ID
base_address	string	none	Base address (hex)
loader	string	none	Loader type

docker_stop

Stop and optionally remove a container. Session-scoped: you can only stop containers started by your own MCP session.

Parameter	Type	Default	Description
name_or_id	string	required	Container name or ID
remove	bool	true	Also remove the container

docker_health

Check if a container’s HTTP API is responding. Tries /health first, then falls back to the root endpoint for older plugin versions.

Parameter	Type	Default	Description
port	int	current	API port to check
timeout	float	5.0	Request timeout in seconds

docker_logs

Get stdout/stderr from a container. Useful for monitoring analysis progress.

Parameter	Type	Default	Description
name_or_id	string	required	Container name or ID
tail	int	100	Number of lines to show
follow	bool	false	Follow log output (not recommended for MCP)

docker_status

List all MCGhidra containers, Docker images, port pool allocation status, and whether Docker/Compose are available.

docker_build

Build the MCGhidra Docker image from source.

Parameter	Type	Default	Description
tag	string	"latest"	Image tag
no_cache	bool	false	Build without Docker cache
project_dir	string	auto	Path to MCGhidra project root

docker_cleanup

Remove orphaned containers and stale port lock files. By default, only cleans containers from the current session for safety.

Parameter	Type	Default	Description
session_only	bool	true	Only clean this session’s containers
max_age_hours	float	24.0	Max age for orphaned containers
dry_run	bool	false	Report what would be cleaned without acting

docker_session_info

Show containers and allocated ports for the current MCP session.