mcp module

Tools for Binary Ninja’s Model Context Protocol (MCP) server.

A tool registered here is offered by every MCP server in the process, alongside the built-in bn_* tools. The simplest way to write one is the tool decorator, which builds the tool’s JSON Schema from the function’s signature and docstring:

from binaryninja import mcp

@mcp.tool(read_only=True)
def myplugin_function_count(call: mcp.ToolCall, min_size: int = 0) -> dict:
        """Count the functions in the active binary view.

        :param min_size: Only count functions with at least this many bytes.
        """
        functions = [f for f in call.binary_view.functions if f.total_bytes >= min_size]
        return {"count": len(functions)}

Class	Description
binaryninja.mcp.Address	A parameter annotated Address accepts an address expression string, evaluated against the…
binaryninja.mcp.ClampTo	Clamps an int parameter’s value to the range minimum to maximum instead of rejecting…
binaryninja.mcp.IntegerExpression	A parameter annotated IntegerExpression accepts an unsigned integer or an expression string,…
binaryninja.mcp.Maximum	Rejects an int parameter’s values above value. Use it as…
binaryninja.mcp.Minimum	Rejects an int parameter’s values below value. Use it as Annotated[int, mcp.Minimum(0)].
binaryninja.mcp.NonEmpty	Rejects an empty str parameter. Use it as Annotated[str, mcp.NonEmpty()].
binaryninja.mcp.RelativeTo	Evaluates an …
binaryninja.mcp.Schema	Supplies the JSON Schema for a parameter the other annotations cannot describe. Use it as…
binaryninja.mcp.Tool	A tool in the tool registry. Iterating over Tool lists every registered tool, sorted by name.
binaryninja.mcp.ToolCall	One invocation of a tool. Once the tool returns, binary_view is None and is_cancelled…
binaryninja.mcp.ToolError	Raised by a tool to return an error result with a machine-readable code.
binaryninja.mcp.ToolResult	The result of a tool. A tool may instead return a str (text), a dict (structured…

Function	Description
binaryninja.mcp.register_tool	Registers a tool for the life of the process.
binaryninja.mcp.tool	Registers the decorated function as a tool. The function’s first parameter receives the…

Address

class Address

Bases: int

A parameter annotated Address accepts an address expression string, evaluated against the call’s binary view. The function receives an int.

ClampTo

class ClampTo

Bases: object

Clamps an int parameter’s value to the range minimum to maximum instead of rejecting values outside it. Use it as Annotated[int, mcp.ClampTo(0, 1000)].

__init__(minimum: int, maximum: int)

Parameters:

• minimum (int)

• maximum (int)

IntegerExpression

class IntegerExpression

Bases: int

A parameter annotated IntegerExpression accepts an unsigned integer or an expression string, evaluated against the call’s binary view. The function receives an int.

Maximum

class Maximum

Bases: object

Rejects an int parameter’s values above value. Use it as Annotated[int, mcp.Maximum(100)].

__init__(value: int)

Parameters:

value (int)

Minimum

class Minimum

Bases: object

Rejects an int parameter’s values below value. Use it as Annotated[int, mcp.Minimum(0)].

__init__(value: int)

Parameters:

value (int)

NonEmpty

class NonEmpty

Bases: object

Rejects an empty str parameter. Use it as Annotated[str, mcp.NonEmpty()].

RelativeTo

class RelativeTo

Bases: object

Evaluates an IntegerExpression parameter’s expression with an earlier Address, IntegerExpression or int parameter’s value as $here. When that argument is absent, its default is used, or 0 when it has none. Use it as Annotated[mcp.IntegerExpression, mcp.RelativeTo("address")], for example for a length measured from an address, or on the items of a List of them.

__init__(parameter: str)

Parameters:

parameter (str)

Schema

class Schema

Bases: object

Supplies the JSON Schema for a parameter the other annotations cannot describe. Use it as Annotated[dict, mcp.Schema({...})]. The function receives the argument as decoded JSON.

__init__(schema: dict)

Parameters:

schema (dict)

Tool

class Tool

Bases: object

A tool in the tool registry. Iterating over Tool lists every registered tool, sorted by name.

__init__(handle)

static by_name(name: str) → Tool | None

Parameters:

name (str)

Return type:

Tool | None

invoke(arguments: dict | None = None, view: BinaryView | None = None) → dict

Runs the tool as an MCP server would, against view, and returns the MCP CallToolResult.

Parameters:

• arguments (dict | None)

• view (BinaryView | None)

Return type:

dict

static list() → List[Tool]

Return type:

List[Tool]

property annotations: McpToolAnnotation

A combination of McpToolAnnotation flags.

property description: str

property input_schema: dict

property name: str

property output_schema: dict | None

property scope: McpToolScope

property title: str

ToolCall

class ToolCall

Bases: object

One invocation of a tool. Once the tool returns, binary_view is None and is_cancelled is True.

__init__(handle)

parse_address(value: Any, here: int = 0) → int

Evaluates an address expression string, with here as the value of $here. Raises ValueError when it is invalid.

Parameters:

• value (Any)

• here (int)

Return type:

int

parse_integer(value: Any, here: int = 0) → int

Evaluates an unsigned integer or an expression string, with here as the value of $here. Raises ValueError when it is invalid.

Parameters:

• value (Any)

• here (int)

Return type:

int

report_progress(progress: float, total: float, message: str = '') → None

Parameters:

• progress (float)

• total (float)

• message (str)

Return type:

None

property binary_view: BinaryView | None

The binary view the MCP session targets. Never None while a BinaryView-scoped tool runs.

property is_cancelled: bool

ToolError

exception ToolError

Bases: Exception

Raised by a tool to return an error result with a machine-readable code.

__init__(code: str, message: str, details: Any = None)

Parameters:

• code (str)

• message (str)

• details (Any)

ToolResult

class ToolResult

Bases: object

The result of a tool. A tool may instead return a str (text), a dict (structured content) or None (an empty result).

__init__(text: str | List[str] | None = None, structured: dict | None = None)

Parameters:

• text (str | List[str] | None)

• structured (dict | None)

add_warning(code: str, message: str) → ToolResult

Adds an advisory warning about the result, such as analysis that has not finished. Clients see it in the structured content’s reserved warnings member, and after any text.

Parameters:

• code (str)

• message (str)

Return type:

ToolResult

static from_error(error: ToolError) → ToolResult

Parameters:

error (ToolError)

Return type:

ToolResult

register_tool

register_tool(name: str, description: str, input_schema: dict, handler: ~typing.Callable[[~binaryninja.mcp.ToolCall, dict], ~typing.Any], *, title: str = '', scope: ~binaryninja.enums.McpToolScope = McpToolScope.BinaryViewScope, annotations: ~binaryninja.enums.McpToolAnnotation = <McpToolAnnotation: 0>, output_schema: dict | None = None) → Tool

Registers a tool for the life of the process.

Parameters:

• handler (Callable[[ToolCall, dict], Any]) – Called as handler(call, arguments) with the decoded arguments object. Returns a str, dict, ToolResult or None, or raises ToolError.

• name (str)

• description (str)

• input_schema (dict)

• title (str)

• scope (McpToolScope)

• annotations (McpToolAnnotation)

• output_schema (dict | None)

Raises:

ValueError – The definition is invalid or its name is already registered.

Return type:

Tool

tool()

tool(name: str | None = None, *, title: str = '', scope: McpToolScope = McpToolScope.BinaryViewScope, read_only: bool = False, destructive: bool = False, idempotent: bool = False, open_world: bool = False, output_schema: dict | None = None)

Registers the decorated function as a tool. The function’s first parameter receives the ToolCall. Every other parameter becomes a tool parameter, and needs a type annotation and a :param name: line in the docstring. The docstring’s leading paragraph becomes the tool’s description.

Supported annotations are str, int, float, bool, Address, IntegerExpression, Binary Ninja enums (by member name), Literal of strings, List[T], Annotated[T, Schema({...})], Annotated[IntegerExpression, RelativeTo("name")], Annotated[str, NonEmpty()] and int annotated with Minimum, Maximum or ClampTo. Optional[T], T | None or a default value makes a parameter optional, and a null argument for one is treated as absent.

Use it with parentheses or without, as @mcp.tool() or @mcp.tool.

The tool’s name defaults to the function’s name. Arguments are checked before the function runs, and a missing, invalid or undeclared argument produces an invalid_params error without calling it.

Parameters:

• name (str | None)

• title (str)

• scope (McpToolScope)

• read_only (bool)

• destructive (bool)

• idempotent (bool)

• open_world (bool)

• output_schema (dict | None)