ImHex MCP Integration

🔧 AI-Powered Binary Analysis with ImHex

Model Context Protocol server enabling AI assistants like Claude to analyze binary files programmatically

⚡ Quick Start • Features • Documentation • Testing • Performance

💡 Overview

ImHex MCP provides a production-ready Python MCP server that connects AI assistants to ImHex, the powerful hex editor. This enables autonomous binary analysis, malware inspection, firmware analysis, and reverse engineering workflows.

What's Included

🔌 MCP Server - 40+ tools for binary analysis (Python)
📦 ImHex Patches - 10 patches adding network interface & queue-based file opening
⚡ Performance Optimizations - 18% faster with caching, compression, async operations
🧪 Comprehensive Testing - 255/255 tests passing (100% success rate)
📊 Production Features - Prometheus metrics, circuit breakers, rate limiting
📖 Complete Documentation - API docs, architecture diagrams, guides

🌟 Features

Core Capabilities

File Operations

Queue-based async file opening (no manual GUI interaction!)
Multi-file management (list, switch, close)
Binary data read/write with multiple encodings

Analysis Tools

Pattern searching (hex, text, regex) with pagination
Multi-architecture disassembly (x86, ARM, MIPS, etc.)
Hash calculation (MD5, SHA-1, SHA-256, SHA-384, SHA-512)
String extraction (ASCII, UTF-16)
File type detection (30+ magic number signatures)
Entropy analysis for encryption detection
Binary diff with Myers algorithm

Batch Operations

Multi-file pattern search
Batch hashing
Comparative analysis across files

Advanced Features

Chunked reading for large files (100MB+)
Data export (binary, hex, base64)
Bookmark management
Pattern Language integration

Python Library Features

Performance (17 improvements, 100% complete)

18% faster overall (0.217s → 0.178s)
98.9% bandwidth reduction with zstd compression
28% faster cache operations with orjson + LRU caching
25% lock reduction with optimized critical sections
97% faster JSON serialization

Production Ready

Async/await support with connection pooling
Response caching with LRU eviction
Retry logic with exponential backoff
Circuit breaker pattern
Prometheus metrics export
Rate limiting & input validation
100% type hints with mypy compliance

🚀 Quick Start

Prerequisites

macOS or Linux
Python 3.10+ (tested on 3.10, 3.11, 3.12, 3.14)
CMake 3.25+
Git
C++ compiler (GCC 11+ or Clang 14+)

One-Command Setup

git clone --recurse-submodules https://github.com/jmpnop/imhexMCP.git
cd imhexMCP
./setup-imhex-mcp.sh

This script:

Clones ImHex repository
Applies all 10 patches automatically
Shows build instructions

Build ImHex

cd ImHex
mkdir -p build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build . -j$(sysctl -n hw.ncpu)  # macOS
# cmake --build . -j$(nproc)            # Linux

Setup MCP Server

cd ../../mcp-server
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Start ImHex & Enable Network Interface

Run ImHex: ./ImHex/build/imhex
Go to Settings → General
Enable Network Interface
Restart ImHex

Network interface listens on localhost:31337

Configure Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "imhex": {
      "command": "/ABSOLUTE/PATH/TO/imhexMCP/mcp-server/venv/bin/python",
      "args": ["/ABSOLUTE/PATH/TO/imhexMCP/mcp-server/server.py"]
    }
  }
}

Important: Use absolute paths, not relative!

Verify Setup

cd imhexMCP
./verify-setup.sh  # Should show 15/15 passed

Test with Claude

In Claude, ask:

Can you check if ImHex is working? Use the imhex_get_capabilities tool.

📖 Key Endpoints

The ImHex MCP plugin provides 28 network endpoints. Here are the most important:

Endpoint	Description	Example Usage
`file/open`	Queue-based async file opening	Open firmware for analysis
`data/read`	Read hex data with encoding options	Extract file headers
`data/search`	Pattern search (hex/text/regex)	Find magic numbers
`data/hash`	Calculate file hashes	Verify file integrity
`data/strings`	Extract ASCII/UTF-16 strings	Find embedded URLs
`data/magic`	File type detection	Identify unknown files
`data/disassemble`	Multi-arch disassembly	Reverse engineer code
`batch/search`	Multi-file pattern search	Malware analysis
`batch/hash`	Batch hash calculation	Forensic analysis
`data/entropy`	Shannon entropy analysis	Detect encryption

Full reference: See ENDPOINTS.md for all 28 endpoints with detailed parameters.

🧪 Testing

Test Suite

255 tests, 100% passing ✅

# Run all tests
pytest

# Run with coverage
pytest --cov=lib --cov=mcp-server --cov-report=term-missing

# Run specific test types
pytest -m unit          # Unit tests only
pytest -m integration   # Integration tests (requires ImHex)
pytest -m compression   # Compression tests

Test Organization

Tests are organized with pytest markers:

@pytest.mark.unit - Fast unit tests (no dependencies)
@pytest.mark.integration - Requires running ImHex
@pytest.mark.slow - Tests taking >1 second
@pytest.mark.compression - Compression module tests

Coverage

Current coverage by module:

error_handling.py: 94%
advanced_features.py: 96%
advanced_cache.py: 92%
batching.py: 90%
security.py: 82%

Target: 80%+ coverage for all modules

⚡ Performance

Overall Improvements

17/17 optimizations complete (100%)

Metric	Baseline	Optimized	Improvement
Total runtime	0.217s	0.178s	18% faster
Function calls	443,231	371,908	16% fewer
Cache operations	0.169s	~0.127s	28% faster
JSON serialization	0.072s	0.002s	97% faster
Lock overhead	24,044 calls	18,024	25% reduction

Key Optimizations

Round 1: orjson + LRU Caching + Fast Size Estimation

orjson for 2-3x faster JSON (24x per call in practice)
LRU-cached key generation with @lru_cache(maxsize=1000)
Direct length calculations for size estimation

Round 2: Compression + Async Lock Optimization

Compression buffer reuse with zlib.compressobj()
Adaptive compression levels (based on data size)
CacheEntry creation moved outside critical section
25% reduction in time.time() calls under lock

Compression Performance

98.9% bandwidth reduction with zstd
Net benefit: 227ms saved per 100 requests (@ 100 Mbps)
Overhead: <1ms compression time for most payloads
Cache speedup: 21,670x faster for metadata

Full details: See lib/PERFORMANCE_RESULTS.md and lib/OPTIMIZATION_RESULTS_ROUND2.md

📂 Project Structure

imhexMCP/
├── lib/                          # Core Python library (production-ready)
│   ├── async_client.py          # Main async client
│   ├── cache.py                 # Response caching (LRU + orjson)
│   ├── data_compression.py      # Adaptive compression
│   ├── connection_pool.py       # Connection pooling
│   ├── request_batching.py      # Batch operations
│   ├── error_handling.py        # Retry logic & circuit breaker
│   ├── security.py              # Input validation & sanitization
│   ├── metrics.py               # Prometheus metrics
│   └── test_*.py                # Test suite (255 tests)
│
├── mcp-server/                  # MCP server implementation
│   ├── server.py                # Main MCP server (2381 lines)
│   ├── enhanced_client.py       # Enhanced client wrapper
│   ├── imhex_cli.py            # CLI interface
│   └── benchmark_*.py          # Performance benchmarks
│
├── patches/                     # Git patches for ImHex
│   ├── PATCH_MANIFEST.md        # Patch documentation
│   ├── 0001-feat-*.patch        # Queue-based file opening
│   └── 0007-0014-*.patch        # Complete MCP plugin
│
├── ImHex/                       # ImHex submodule (1.38.0.WIP)
│   └── build/imhex             # ImHex binary
│
├── docs/                        # Comprehensive documentation
│   ├── LIBRARY-ARCHITECTURE.md # 15+ Mermaid diagrams
│   ├── API.md                  # API reference
│   └── ...
│
├── CLAUDE.md                    # AI assistant context
├── README.md                    # This file
└── setup-imhex-mcp.sh          # Automated setup script

🏗️ Architecture

┌─────────────────────┐
│   User / AI         │  Analyze binaries via Claude
└──────────┬──────────┘
           │ MCP Protocol (stdio)
┌──────────▼──────────┐
│   MCP Server        │  Python server (40+ tools)
│   - Request handling│  • Async operations
│   - Caching         │  • Connection pooling
│   - Compression     │  • Performance optimization
└──────────┬──────────┘
           │ JSON-RPC over TCP
┌──────────▼──────────┐
│   ImHex             │  Hex editor with network interface
│   Network Interface │  • Listens on localhost:31337
└──────────┬──────────┘
           │ Plugin API
┌──────────▼──────────┐
│   MCP Plugin        │  C++ plugin (patched)
│   - File operations │  • Queue-based file opening
│   - Data analysis   │  • 28 network endpoints
│   - Batch ops       │  • Enhanced error handling
└──────────┬──────────┘
           │ ImHex APIs
┌──────────▼──────────┐
│   ImHex Core        │
│   - FileProvider    │
│   - Pattern Engine  │
│   - Crypto Library  │
└─────────────────────┘

📊 Improvements Summary

Status: 17/17 complete (100%) 🎉

Critical Improvements

✅ Pytest Framework - Professional test suite (255 tests, 100% passing)
✅ CI/CD Pipeline - GitHub Actions (tests, security, lint, benchmarks)
✅ Type Hints - 100% mypy compliance
✅ Python 3.14 Compatibility - All tests passing
✅ Test Suite Fixes - From 86% to 100% pass rate

Performance & Optimization

✅ Performance Profiling - cProfile analysis, bottleneck identification
✅ Optimization Round 1 - orjson, LRU caching (18% faster)
✅ Optimization Round 2 - Compression, async locks (25% lock reduction)

Security & Quality

✅ Security Hardening - Rate limiting, input validation, SQL injection prevention
✅ Code Quality Tools - Black, flake8, mypy
✅ Centralized Config - Pydantic-based validation

Documentation

✅ Sphinx API Documentation - 100% module coverage (21 modules)
✅ Architecture Diagrams - 15+ Mermaid diagrams
✅ Property-Based Testing - Hypothesis integration
✅ Prometheus Metrics - Production monitoring

Full details: See IMPROVEMENTS-SUMMARY.md

💻 Platform Support

Tested Platforms

✅ macOS ARM64 (Apple Silicon) - Native build
✅ macOS x86_64 (Intel) - Full support

Should Work (Untested)

⚠️ Linux x86_64 - Standard ImHex build process
⚠️ Windows - Via MSYS2/MinGW64

🤝 Contributing

We welcome contributions!

Areas for Help

🐛 Bug fixes and issue reports
📝 Documentation improvements
🧪 Testing on different platforms
✨ New features and endpoints

Contribution Workflow

Fork this repository
Clone ImHex and apply patches
Make your changes
Run tests: pytest
Generate new patches: git format-patch origin/master..HEAD
Submit PR with updated patches

📄 Documentation

Document	Description
CLAUDE.md	Complete project context for AI assistants
patches/PATCH_MANIFEST.md	Patch documentation and application order
docs/LIBRARY-ARCHITECTURE.md	Architecture diagrams and design
lib/PERFORMANCE_RESULTS.md	Performance optimization results
TESTING.md	Testing guide and best practices
docs/SECURITY.md	Security guidelines
docs/API.md	API reference

🔗 Related Projects

ImHex - Feature-rich hex editor by WerWolv
MCP Specification - Model Context Protocol by Anthropic
Claude - AI assistant with MCP support

📞 Support

Get Help

📖 Documentation: Start with CLAUDE.md
🐛 Issues: GitHub Issues
💬 Discussions: GitHub Discussions

Report Issues

Please include:

ImHex commit hash
Operating system and architecture
Python version
Error messages
Steps to reproduce

📄 License

GPL-2.0 - Same as ImHex

This project provides a Model Context Protocol server and patches for ImHex, following its licensing terms. See LICENSE for full text.

🙏 Credits

ImHex by WerWolv - The amazing hex editor
Model Context Protocol by Anthropic - Protocol specification
The reverse engineering community for feedback and testing

⭐ Star this repository if you find it useful!

Made with ❤️ for the reverse engineering community

Report Bug · Request Feature · Documentation

Version 2.0.0 | Last Updated: 2025-11-15 | Status: ✅ Production Ready

Name		Name	Last commit message	Last commit date
Latest commit History 105 Commits
.github		.github
benchmarks		benchmarks
docs		docs
examples		examples
lib		lib
mcp-server		mcp-server
patches		patches
plugin		plugin
scripts		scripts
tests		tests
.flake8		.flake8
.gitignore		.gitignore
.gitmodules		.gitmodules
.mutmut_config.py		.mutmut_config.py
.pre-commit-config.yaml		.pre-commit-config.yaml
CLAUDE.md		CLAUDE.md
ENDPOINTS.md		ENDPOINTS.md
IMPROVEMENTS-SUMMARY.md		IMPROVEMENTS-SUMMARY.md
LICENSE		LICENSE
README.md		README.md
TESTING.md		TESTING.md
apply-patches.sh		apply-patches.sh
config.yaml		config.yaml
config.yaml.example		config.yaml.example
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini
revert-patches.sh		revert-patches.sh
setup-imhex-mcp.sh		setup-imhex-mcp.sh
verify-setup.sh		verify-setup.sh

License

jmpnop/imhexMCP

Folders and files

Latest commit

History

Repository files navigation

ImHex MCP Integration

💡 Overview

What's Included

🌟 Features

Core Capabilities

Python Library Features

🚀 Quick Start

Prerequisites

One-Command Setup

Build ImHex

Setup MCP Server

Start ImHex & Enable Network Interface

Configure Claude Desktop

Verify Setup

Test with Claude

📖 Key Endpoints

🧪 Testing

Test Suite

Test Organization

Coverage

⚡ Performance

Overall Improvements

Key Optimizations

Compression Performance

📂 Project Structure

🏗️ Architecture

📊 Improvements Summary

Critical Improvements

Performance & Optimization

Security & Quality

Documentation

💻 Platform Support

Tested Platforms

Should Work (Untested)

🤝 Contributing

Areas for Help

Contribution Workflow

📄 Documentation

🔗 Related Projects

📞 Support

Get Help

Report Issues

📄 License

🙏 Credits

About

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors 2

Uh oh!

Languages

Packages