kuna_mcp

kuna_mcp is a Python MCP server for targeted binary analysis with Kuna. It exposes Kuna through MCP's Streamable HTTP transport, so MCP clients communicate with it using JSON-RPC at http://127.0.0.1:8000/mcp by default.

The project and Python package are named kuna_mcp; the installed shell command uses the conventional executable spelling kuna-mcp.

Whole-binary decompilation is deliberately not exposed. Large binaries can take a long time and produce far more context than an AI can use safely.

MCP tools

• list_functions — list functions as structured JSON, with pagination when Kuna returns a JSON list.
• decompile_function — decompile one function by name or hexadecimal VMA.
• decompile_functions — decompile a bounded list concurrently and return one response. Individual failures are preserved alongside successful results.

The server does not expose decompile-all or decompile-project.

Release status

The current release is 0.1.0: the first usable version of kuna_mcp. The server, installer, real Kuna integration, and HTTP transport are functional, but the public MCP tool schemas may still evolve before the 1.0.0 compatibility milestone.

Install

Requirements are Python 3.10+, a Rust toolchain, make, and git.

./install.sh

The installer initializes the Kuna submodule, runs make binaries and make specs, creates .venv, and installs this package. Kuna's executable is expected at kuna/decompiler/target/release/kuna and its specifications at kuna/specs.

For Python-only development (using an existing Kuna installation):

python3 -m venv .venv
.venv/bin/pip install -e '.[dev]'

Run over HTTP

.venv/bin/kuna-mcp

Options and their environment equivalents:

--host  KUNA_MCP_HOST  default: 127.0.0.1
--port  KUNA_MCP_PORT  default: 8000
--path  KUNA_MCP_PATH  default: /mcp

Example:

.venv/bin/kuna-mcp --host 0.0.0.0 --port 8080

The default loopback binding is intentional. If you bind to a public or shared interface, put the server behind authentication and TLS; every authenticated client can request reads of binaries allowed by KUNA_ALLOWED_BINARY_ROOTS.

Connect an MCP client to http://127.0.0.1:8000/mcp. The server uses stateless Streamable HTTP with JSON responses; the MCP SDK performs initialization, JSON-RPC validation, tool discovery, input-schema validation, and response framing.

Use with an MCP client

Start kuna-mcp, then register the following Streamable HTTP endpoint in your MCP client:

http://127.0.0.1:8000/mcp

For clients that accept JSON server configuration, the entry normally has this shape (the surrounding configuration filename varies by client):

{
  "mcpServers": {
    "kuna": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

Once connected, ask the client to list functions before requesting targeted decompilation. For example:

List the first 50 functions in /bin/ls with Kuna.
Decompile function sub_187d0 from /bin/ls.
Decompile addresses 0x187d0 and 0x18940 from /bin/ls in one request.

The same flow can be exercised with the MCP Python client:

import asyncio
from mcp import Client


async def main():
    async with Client("http://127.0.0.1:8000/mcp") as client:
        functions = await client.call_tool(
            "list_functions",
            {"binary_path": "/bin/ls", "offset": 0, "limit": 10},
        )
        print(functions.structured_content)


asyncio.run(main())

MCP Inspector

With Node.js available, start the server and connect the MCP Inspector to the URL above:

npx -y @modelcontextprotocol/inspector

Configuration and limits

All values are read when the server starts.

Variable	Default	Purpose
KUNA_BINARY	./kuna/decompiler/target/release/kuna	Kuna executable
KUNA_SLEIGH_PATH	./kuna/specs	Compiled SLEIGH specifications
KUNA_ALLOWED_BINARY_ROOTS	project root, /bin, /usr/bin	Allowed input roots, separated by : on Unix
KUNA_TIMEOUT_SECONDS	120	Timeout for each Kuna process
KUNA_MAX_BATCH_SIZE	20	Maximum functions in one batch
KUNA_MAX_CONCURRENCY	4	Maximum simultaneous Kuna processes
KUNA_MAX_OUTPUT_BYTES	8388608	Maximum stdout bytes per Kuna call

Set the allow-list to every directory containing binaries the MCP may inspect:

KUNA_ALLOWED_BINARY_ROOTS=/samples:/opt/firmware .venv/bin/kuna-mcp

Resolved paths must remain below one of those roots, so symlinks cannot escape the allow-list. Kuna is always launched without a shell.

Example tool arguments

List functions:

{
  "binary_path": "/bin/ls",
  "mode": "auto",
  "offset": 0,
  "limit": 500
}

Decompile by name:

{
  "binary_path": "/bin/ls",
  "function": "sub_187d0"
}

Decompile several addresses in one request:

{
  "binary_path": "/bin/ls",
  "functions": ["0x187d0", "0x18940"],
  "by_address": true,
  "mode": "reliable"
}

Test

Install the development dependencies and run the fast test suite:

.venv/bin/pip install -e '.[dev]'
.venv/bin/pytest -q

These tests use a controlled fake Kuna executable and an in-memory MCP client, so they validate command construction, pagination, validation, partial batch failures, structured MCP results, and exposed tool names without requiring a Kuna rebuild.

To test the relevant Kuna CLI surface itself:

source "$HOME/.cargo/env"
cargo test --manifest-path kuna/decompiler/Cargo.toml \
  -p kuna-cli --test decompile_all_cli

End-to-end HTTP test

Terminal 1:

.venv/bin/kuna-mcp

Terminal 2:

.venv/bin/python scripts/http_smoke_test.py \
  --url http://127.0.0.1:8000/mcp \
  --binary /bin/ls

The smoke test connects through HTTP, initializes MCP/JSON-RPC, discovers the tools, lists functions with the real Kuna executable, and decompiles the first non-header function by address. A successful run exits with status zero.

Only analyze binaries you are legally authorized to inspect.

https://github.com/user-attachments/assets/47458d03-e454-43ab-acc8-2a4e57a201de