HopperPyMCP - FastMCP Server for Hopper Disassembler
A FastMCP server plugin for the Hopper disassembler that provides powerful analysis tools through the Model Context Protocol (MCP). This plugin allows you to analyze binary files, disassemble procedures, manage documents, and more through AI assistants.
Features
- 🔍 Binary Analysis: Analyze segments, procedures, and data structures
- 🛠️ Disassembly & Decompilation: Get detailed assembly and pseudo-code output
- 📊 Call Graph Generation: Visualize function relationships and program flow
- 🔗 Reference Analysis: Track memory references and cross-references
- 📝 Annotation Tools: Add names, comments, and type information
- 🗂️ Document Management: Handle multiple executable files
- 🔍 String Search: Advanced regex-based string searching
Quick Installation
The installation process automatically detects your Python environment (conda, uv, venv, or system Python) and configures everything for you:
That's it! The script will:
- ✅ Detect your Python environment automatically
- ✅ Install required dependencies (fastmcp)
- ✅ Configure the script with correct Python paths
- ✅ Install to the appropriate Hopper Scripts directory
Supported Environments
- Conda environments (including miniconda/anaconda)
- UV virtual environments
- Python venv/virtualenv
- System Python installations
- macOS and Linux platforms
If you use an environment like conda, uv, or virtualenv, run the install script from within a new environment, since dependencies will be installed by install.py.
Manual Installation Options
Dry Run (Preview Changes)
Force Installation
Uninstallation
Remove the plugin cleanly:
Usage in Hopper
Once installed, the FastMCP server will be available as a script in Hopper.
Starting the Server
After running the script in Hopper, you'll need to launch the MCP server through the Python prompt:
- First Time Setup - Cache Strings (Recommended)Due to slow Hopper string APIs, the plugin creates optimized string caches for better performance. This process takes about 5-10 minutes per document and saves caches alongside your Hopper document saves.In the Hopper Python prompt, paste:Wait for caching to complete, then launch the server:
- Quick Start (Skip Caching)To start immediately without caching (slower string searches):
- Subsequent UsesIf you've already cached strings for your documents:
The server will run on http://localhost:42069/mcp/
and provide the following tools:
Document Management
get_all_documents()
- Get information about all currently opened documents (Hopper-analyzed binaries)get_current_document()
- Get information about the current document with its doc_idset_current_document(doc_id)
- Set the current document by doc_idrebase_document(new_base_address_hex)
- Rebase the current document to a new base address
Core Analysis Tools
list_all_segments()
- List all segments in the current document with basic informationget_address_info(address_or_name_list)
- Get comprehensive information about multiple addresses/names including segment, section, type, procedure info, and references
Search and Discovery
search_names_regex(regex_pattern, segment_name, search_type, max_results)
- Search for names matching a regex pattern in a specific segmentsearch_strings_regex(regex_pattern, segment_name, max_results)
- Search for strings matching a regex pattern in a specific segmentget_string_at_addr(address_hex)
- Get the string content at a specific address using the cached strings list
Disassembly & Decompilation
disassemble_procedure(address_or_name)
- Disassemble a procedure into assembly language instructionsdecompile_procedure(address_or_name)
- Decompile a procedure to C language code
Call Graph Generation
get_call_graph(start_addr_hex, direction, max_depth)
- Return the call graph starting from a specific address
Name and Symbol Analysis
get_demangled_name(address_or_name)
- Get the demangled name at a specific address or for a given name
Comments and Annotations
get_comment_at_address(address_hex)
- Get the comment at a specific addressset_comment_at_address(address_hex, comment)
- Set a comment at a specific addressset_name_at_address(address_hex, name)
- Set a name/label at a specific addressmark_data_type_at_address(address_hex, data_type, length)
- Mark data type at a specific address
Requirements
- Python 3.8+
- Hopper Disassembler v4 or v5
- FastMCP library (automatically installed)
File Structure
Troubleshooting
Installation Issues
Problem: fastmcp
import fails after installation
Problem: Permission denied when writing to Hopper directory
Problem: Wrong Python environment detected
Runtime Issues
Problem: Script not appearing in Hopper
- Verify installation path is correct for your platform
- Check Hopper Scripts directory exists and is readable
- Restart Hopper after installation
Problem: Import errors when running in Hopper
- The installation should handle Python path configuration automatically
- If issues persist, check that the installed script has the correct paths
Platform-Specific Notes
macOS: Scripts install to ~/Library/Application Support/Hopper/Scripts/
Linux: Scripts install to ~/GNUstep/Library/ApplicationSupport/Hopper/Scripts/
Development
Running Tests
Development Installation
For development, you might want to symlink instead of copy:
Support
For issues and questions:
- Check the troubleshooting section above
- Review the test files for usage examples
- Open an issue on the project repository
Note: This plugin requires Hopper's built-in Python interpreter. The installation script automatically configures the necessary Python paths for seamless integration.
This server cannot be installed
A FastMCP server plugin for the Hopper disassembler that enables AI assistants to analyze binary files, disassemble procedures, generate call graphs, search strings, and manage reverse engineering tasks. Provides comprehensive binary analysis capabilities including decompilation, annotation tools, and reference tracking through natural language interactions.