Search tools: bytes, instructions, and string patterns

The search tools scan the binary and the IDA database for byte patterns, instruction sequences, string contents, and cross-references to specific values or addresses. All search tools return a cursor field that lets you page through large result sets without re-running the scan from the beginning.

Pagination model

Every search result includes a cursor field:

{"next": N} — more results exist. Pass offset=N on the next call to resume.
{"done": true} — you have received all results.

The default and maximum limits vary per tool. Stay within the documented caps to avoid token overflow.

`find_regex`

Searches IDA’s string cache for strings matching a case-insensitive regular expression. The cache must be built before use — call server_warmup with build_caches=True at the start of a session.

pattern

string

required

Python-compatible regular expression to match against string contents.

limit

integer

default:"30"

Maximum matches to return. Hard-capped at 500.

offset

integer

default:"0"

Skip the first N matches (pagination).

Returns: FindRegexResult

integer

required

Number of matches returned in this page.

matches

array

required

List of {addr, string} records.

cursor

object

required

{"next": N} or {"done": true}.

error

string

Present when the search fails (e.g. invalid regex).

result = mcp.call_tool("find_regex", {"pattern": "password|secret|key"})
for m in result["matches"]:
    print(m["addr"], repr(m["string"]))

find_regex searches only the pre-built strings cache. It does not scan raw bytes. Use find with type="string" for a raw byte search.

`find_bytes`

Searches the entire binary for byte patterns using ?? as a wildcard for any single byte. Results are paginated by offset.

patterns

string | list[string]

required

Byte pattern(s) to search for. Space-separate bytes in hex; use ?? for wildcard bytes (e.g. "48 8B ?? ??", "E8 ?? ?? ?? ??").

limit

integer

default:"1000"

Maximum matches per pattern. Hard-capped at 10 000.

offset

integer

default:"0"

Skip the first N matches (pagination).

Returns: list[FindBytesResult] — one result per input pattern.

pattern

string

required

The input pattern.

matches

array

required

List of hex addresses where the pattern was found.

integer

required

Number of matches returned.

cursor

object

required

{"next": N} or {"done": true}.

error

string

Present when the pattern is invalid or the search fails.

results = mcp.call_tool("find_bytes", {
    "patterns": ["E8 ?? ?? ?? ??"],
    "limit": 100,
})
for addr in results[0]["matches"]:
    print(addr)

Keep limit below 10 000 to avoid exceeding the MCP token budget. For whole-binary scans of common patterns, paginate with offset.

`insn_query`

Queries instructions by mnemonic and/or operand values, with scoped scanning restricted to a function, segment, or address range. This is more precise than find_bytes because it operates on decoded instructions, not raw bytes.

queries

InsnPattern | list[InsnPattern]

required

One or more instruction patterns.

Show InsnPattern fields

mnem

string

Mnemonic to match (case-insensitive, e.g. "call", "mov", "cmp"). Omit or use "*" to match all mnemonics.

op0

integer

Required value for the first operand.

op1

integer

Required value for the second operand.

op2

integer

Required value for the third operand.

op_any

integer

Match any single operand with this value.

func

string

Scope scan to this function address or name.

segment

string

Scope scan to this segment name.

start

string

Scope scan starting from this address.

end

string

Scope scan ending at this address (exclusive).

offset

integer

default:"0"

Pagination offset.

count

integer

default:"100"

Maximum results. Hard-capped at 5 000.

max_scan_insns

integer

default:"200000"

Maximum instructions to scan before stopping. Hard-capped at 2 000 000.

allow_broad

boolean

default:"false"

Allow scanning all executable segments when no scope is specified. Requires explicit opt-in to avoid accidentally scanning the entire binary.

include_fn

boolean

default:"false"

Attach enclosing function metadata to each match.

include_disasm

boolean

default:"false"

Include disassembly text for each match.

Returns: list[InsnQueryResult] — each result has query (summary), ranges (scanned ranges), matches, count, cursor, scanned, truncated, next_start, and optional error.

results = mcp.call_tool("insn_query", {
    "queries": [{"mnem": "int3", "func": "main", "include_disasm": True}]
})
for m in results[0]["matches"]:
    print(m["addr"], m.get("disasm"))

Always specify a scope (func, segment, start/end) when searching for common mnemonics. Without a scope, allow_broad must be True and the scan may be slow on large binaries.

`find`

Advanced search for four types of targets: raw string bytes, immediate values in instructions, data references, and code references. All types share the same pagination model.

type

string

required

Search type: "string", "immediate", "data_ref", or "code_ref".

targets

string | integer | list

required

One or more search targets:

"string" — UTF-8 substrings to search for as raw bytes.
"immediate" — integer values (in executable segments only).
"data_ref" / "code_ref" — addresses to find data or code references to.

limit

integer

default:"1000"

Maximum matches per target. Hard-capped at 10 000.

offset

integer

default:"0"

Pagination offset.

Returns: list[FindResult] — one result per target, each with query, matches (list of hex addresses), count, cursor, and optional error.

results = mcp.call_tool("find", {
    "type": "string",
    "targets": ["Hello, World!"],
})
print(results[0]["matches"])

`search_text`

Searches the IDA rendered listing (disassembly view) using IDA’s native fast text search. Unlike find_regex, this searches disassembly text and comments, not just string data.

pattern

string

required

Text to search for. Treated as a literal substring by default.

limit

integer

default:"30"

Maximum hits per page. Hard-capped at 500.

start

string

default:""

Resume cursor: hex address or symbol to start from. Leave empty to scan from the first segment.

regex

boolean

default:"false"

Treat pattern as a regular expression.

case_sensitive

boolean

default:"false"

Case-sensitive match.

include

string

default:"all"

Which listing lines to include: "disasm", "comments", or "all".

code_only

boolean

default:"true"

Restrict search to executable segments only.

Returns: SearchTextResult

integer

required

Number of hits in this page.

hits

array

required

List of SearchTextHit records. Each has addr, optional function and segment names, and matches (list of {kind, text} where kind is "disasm" or "comment").

cursor

object

required

{"next": "0xNNNN"} (hex address string) or {"done": true}.

error

string

Present when the pattern is invalid or search fails.

result = mcp.call_tool("search_text", {"pattern": "strcmp"})
for hit in result["hits"]:
    print(hit["addr"], hit.get("function", "?"))
    for line in hit["matches"]:
        print(" ", line["kind"], line["text"])

The search_text cursor is an address string (e.g. "0x401234"), not an integer offset. Pass it directly to the start parameter on the next call.

Core & Analysis

Modification

Advanced

Search tools: bytes, instructions, and string patterns

`find_regex`

`find_bytes`

`insn_query`

`find`

`search_text`

Build docs developers (and LLMs) love

Core & Analysis

Modification

Advanced

Documentation Index

​Pagination model

​find_regex

​find_bytes

​insn_query

​find

​search_text

Build docs developers (and LLMs) love

Pagination model

`find_regex`

`find_bytes`

`insn_query`

`find`

`search_text`