Skip to content
Back to search

HopperPyMCP

A Python-Based MCP Server for Hopper Disassembler

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/dflatline--hopperpymcp/badge.svg)](/listings/dflatline--hopperpymcp)

HTML

<a href="/listings/dflatline--hopperpymcp"><img src="/api/listings/dflatline--hopperpymcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

The installation process automatically detects your Python environment (conda, uv, venv, or system Python) and configures everything for you:

# Simple one-command installation
python install.py

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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 231 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # HopperPyMCP - FastMCP Server for Hopper Disassembler
  2. 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.
  3. ## Features
  4. - 🔍 **Binary Analysis**: Analyze segments, procedures, and data structures
  5. - 🛠️ **Disassembly & Decompilation**: Get detailed assembly and pseudo-code output
  6. - 📊 **Call Graph Generation**: Visualize function relationships and program flow
  7. - 🔗 **Reference Analysis**: Track memory references and cross-references
  8. - 📝 **Annotation Tools**: Add names, comments, and type information
  9. - 🗂️ **Document Management**: Handle multiple executable files
  10. - 🔍 **String Search**: Advanced regex-based string searching
  11. ## Quick Installation
  12. The installation process automatically detects your Python environment (conda, uv, venv, or system Python) and configures everything for you:
  13. ```bash
  14. # Simple one-command installation
  15. python install.py
  16. ```
  17. That's it! The script will:
  18. - ✅ Detect your Python environment automatically
  19. - ✅ Install required dependencies (fastmcp)
  20. - ✅ Configure the script with correct Python paths
  21. - ✅ Install to the appropriate Hopper Scripts directory
  22. ### Supported Environments
  23. - **Conda environments** (including miniconda/anaconda)
  24. - **UV virtual environments**
  25. - **Python venv/virtualenv**
  26. - **System Python installations**
  27. - **macOS and Linux platforms**
  28. 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.
  29. ## Manual Installation Options
  30. ### Dry Run (Preview Changes)
  31. ```bash
  32. # See what would be installed without making changes
  33. python install.py --dry-run
  34. ```
  35. ### Force Installation
  36. ```bash
  37. # Overwrite existing installation without prompting
  38. python install.py --force
  39. ```
  40. ## Uninstallation
  41. Remove the plugin cleanly:
  42. ```bash
  43. # Remove the installation
  44. python uninstall.py
  45. # Preview what would be removed
  46. python uninstall.py --dry-run
  47. # Remove without confirmation
  48. python uninstall.py --confirm
  49. ```
  50. ## Usage in Hopper
  51. Once installed, the FastMCP server will be available as a script in Hopper.
  52. ### Starting the Server
  53. After running the script in Hopper, you'll need to launch the MCP server through the Python prompt:
  54. 1. **First Time Setup - Cache Strings (Recommended)**
  55. 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.
  56. In the Hopper Python prompt, paste:
  57. ```python
  58. cache_strings()
  59. ```
  60. Wait for caching to complete, then launch the server:
  61. ```python
  62. launch_server()
  63. ```
  64. 2. **Quick Start (Skip Caching)**
  65. To start immediately without caching (slower string searches):
  66. ```python
  67. launch_server()
  68. ```
  69. 3. **Subsequent Uses**
  70. If you've already cached strings for your documents:
  71. ```python
  72. launch_server()
  73. ```
  74. The server will run on `http://localhost:42069/mcp/` and provide the following tools:
  75. ### Document Management
  76. - [`get_all_documents()`](fastmcp_server_template.py:329) - Get information about all currently opened documents (Hopper-analyzed binaries)
  77. - [`get_current_document()`](fastmcp_server_template.py:355) - Get information about the current document with its doc_id
  78. - [`set_current_document(doc_id)`](fastmcp_server_template.py:386) - Set the current document by doc_id
  79. - [`rebase_document(new_base_address_hex)`](fastmcp_server_template.py:408) - Rebase the current document to a new base address
  80. ### Core Analysis Tools
  81. - [`list_all_segments()`](fastmcp_server_template.py:424) - List all segments in the current document with basic information
  82. - [`get_address_info(address_or_name_list)`](fastmcp_server_template.py:641) - Get comprehensive information about multiple addresses/names including segment, section, type, procedure info, and references
  83. ### Search and Discovery
  84. - [`search_names_regex(regex_pattern, segment_name, search_type, max_results)`](fastmcp_server_template.py:459) - Search for names matching a regex pattern in a specific segment
  85. - [`search_strings_regex(regex_pattern, segment_name, max_results)`](fastmcp_server_template.py:567) - Search for strings matching a regex pattern in a specific segment
  86. - [`get_string_at_addr(address_hex)`](fastmcp_server_template.py:618) - Get the string content at a specific address using the cached strings list
  87. ### Disassembly & Decompilation
  88. - [`disassemble_procedure(address_or_name)`](fastmcp_server_template.py:1008) - Disassemble a procedure into assembly language instructions
  89. - [`decompile_procedure(address_or_name)`](fastmcp_server_template.py:973) - Decompile a procedure to C language code
  90. ### Call Graph Generation
  91. - [`get_call_graph(start_addr_hex, direction, max_depth)`](fastmcp_server_template.py:819) - Return the call graph starting from a specific address
  92. ### Name and Symbol Analysis
  93. - [`get_demangled_name(address_or_name)`](fastmcp_server_template.py:1086) - Get the demangled name at a specific address or for a given name
  94. ### Comments and Annotations
  95. - [`get_comment_at_address(address_hex)`](fastmcp_server_template.py:1115) - Get the comment at a specific address
  96. - [`set_comment_at_address(address_hex, comment)`](fastmcp_server_template.py:1133) - Set a comment at a specific address
  97. - [`set_name_at_address(address_hex, name)`](fastmcp_server_template.py:1155) - Set a name/label at a specific address
  98. - [`mark_data_type_at_address(address_hex, data_type, length)`](fastmcp_server_template.py:1173) - Mark data type at a specific address
  99. ## Requirements
  100. - Python 3.8+
  101. - Hopper Disassembler v4 or v5
  102. - FastMCP library (automatically installed)
  103. ## File Structure
  104. ```
  105. HopperPyMCP/
  106. ├── install.py # Main installation script
  107. ├── uninstall.py # Uninstallation script
  108. ├── fastmcp_server.py # Current working version
  109. ├── fastmcp_server_template.py # Template with placeholders
  110. ├── requirements.txt # Python dependencies
  111. ├── tests/ # Test suite
  112. └── README.md # This file
  113. ```
  114. ## Troubleshooting
  115. ### Installation Issues
  116. **Problem**: `fastmcp` import fails after installation
  117. ```bash
  118. # Solution: Manually install dependencies
  119. pip install fastmcp
  120. # or for conda:
  121. conda install -c conda-forge fastmcp
  122. ```
  123. **Problem**: Permission denied when writing to Hopper directory
  124. ```bash
  125. # Solution: Check Hopper directory permissions
  126. ls -la ~/Library/Application\ Support/Hopper/Scripts/ # macOS
  127. ls -la ~/GNUstep/Library/ApplicationSupport/Hopper/Scripts/ # Linux
  128. ```
  129. **Problem**: Wrong Python environment detected
  130. ```bash
  131. # Solution: Activate the correct environment first
  132. conda activate your-environment # for conda
  133. source your-venv/bin/activate # for venv
  134. # Then run install.py
  135. ```
  136. ### Runtime Issues
  137. **Problem**: Script not appearing in Hopper
  138. - Verify installation path is correct for your platform
  139. - Check Hopper Scripts directory exists and is readable
  140. - Restart Hopper after installation
  141. **Problem**: Import errors when running in Hopper
  142. - The installation should handle Python path configuration automatically
  143. - If issues persist, check that the installed script has the correct paths
  144. ### Platform-Specific Notes
  145. **macOS**: Scripts install to `~/Library/Application Support/Hopper/Scripts/`
  146. **Linux**: Scripts install to `~/GNUstep/Library/ApplicationSupport/Hopper/Scripts/`
  147. ## Development
  148. ### Running Tests
  149. ```bash
  150. # Run the test suite
  151. python -m pytest tests/
  152. ```
  153. ### Development Installation
  154. For development, you might want to symlink instead of copy:
  155. ```bash
  156. # Manual symlink for development
  157. ln -s $(pwd)/fastmcp_server.py ~/Library/Application\ Support/Hopper/Scripts/
  158. ```
  159. ## Support
  160. For issues and questions:
  161. 1. Check the troubleshooting section above
  162. 2. Review the test files for usage examples
  163. 3. Open an issue on the project repository
  164. ---
  165. **Note**: This plugin requires Hopper's built-in Python interpreter. The installation script automatically configures the necessary Python paths for seamless integration.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.