Tenrec

A headless, extendable, multi-session MCP framework for IDA Pro, built with ida-domain and FastMCP.

Features

• Headless: No GUI required, powered by ida-domain
• Multi-session: Analyze multiple binaries simultaneously
• Extensible: Custom plugin support via entry points
• Auto-docs: Generate documentation from plugins

Built-in Plugins

Plugin	Description
Functions	Analyze functions, boundaries, pseudocode
Xrefs	Data and code cross-references
Names	Symbol naming and demangling
Comments	Code comments (regular, repeatable)
Strings	String literal search/analysis
Segments	Memory segment queries
Bytes	Binary data read/patch
Types	Type information and structures
Entries	Entry points and exports

For complete plugin documentation, see tenrec docs.

Demo

Solving Flare-On 9 Challenge 4 (darn mice) with a single prompt using tenrec and Claude Code:

Use tenrec to open a session and reverse the binary. Focus on getting a high-level understanding by finding entry points and tracing execution flow. Rename variables and functions as you work. The xref plugin can help. Look for a flag in email format.

https://github.com/user-attachments/assets/3eb442dd-9b7a-44a6-836b-b73f99f4c2f3

Challenge write-up: 04-darn-mice.pdf | Binary: fareedfauzi/Flare-On-Challenges

Installation

Prerequisites

• Python 3.10+
• IDA Pro 9.1+

Install

uv tool install tenrec

Verify installation:

uv tool list    # Should show tenrec
which tenrec    # Should show path to executable

Set IDA Directory

# macOS
export IDADIR="/Applications/IDA Professional 9.1.app/Contents/MacOS"

# Linux
export IDADIR="/opt/idapro"

# Windows (PowerShell, as Administrator)
setx IDADIR "C:\Program Files\IDA Pro" /M

Quick Start

1. Install MCP Client

tenrec install

Select your MCP client from the list (Claude Code, Cursor, Windsurf, etc.).

2. Run Server

tenrec run

The server runs with stdio transport by default. Use --transport sse for SSE.

3. Plugin Management

# Add plugin
tenrec plugins add --plugin "package-name"
tenrec plugins add --plugin "/path/to/plugin"
tenrec plugins add --plugin "git+https://github.com/user/repo"

# List plugins
tenrec plugins list

# Remove plugin
tenrec plugins remove --dist plugin_name

4. Generate Documentation

tenrec docs -p tenrec/plugins/plugins

Documentation

Guide	Description
Plugin Development	Creating custom plugins
CLI Reference	Complete command reference
Architecture	System design
Testing	Testing patterns
Integrations	MCP client setup (including Codex)
Contributing	Development setup and guidelines
Roadmap	Future plans

Creating Plugins

from tenrec.plugins.models import PluginBase, Instructions, operation

class MyPlugin(PluginBase):
    """Plugin description."""

    name = "my_plugin"  # Must be snake_case
    version = "1.0.0"   # Must be semver

    instructions = Instructions(
        purpose="What this plugin does",
        interaction_style=["How to use effectively"],
        examples=["my_plugin_operation()"],
        anti_examples=["What NOT to do"],
    )

    @operation()
    def my_operation(self) -> dict:
        """Operation docstring for LLM guidance."""
        # Access IDA via self.database
        return {"result": "value"}

Package with entry point in pyproject.toml:

[project.entry-points."tenrec.plugins"]
my_plugin = "my_package:MyPlugin"

See Plugin Development Guide for complete documentation.

Known Issues

• Windows support is in progress. See Issue #9.

Contributing

See Contributing Guide for development setup and guidelines.

License

MIT