{"id":50134971,"url":"https://github.com/bethington/cheat-engine-server-python","last_synced_at":"2026-05-23T21:04:38.186Z","repository":{"id":307500606,"uuid":"1029364730","full_name":"bethington/cheat-engine-server-python","owner":"bethington","description":"MCP Cheat Engine Server — provides safe, structured read-only access to memory analysis and debugging functionality through the Model Context Protocol (MCP). For developers, security researchers, and game modders.","archived":false,"fork":false,"pushed_at":"2026-01-29T07:47:32.000Z","size":365,"stargazers_count":17,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-29T22:53:55.738Z","etag":null,"topics":["cheat-engine","debugging","mcp","memory-analysis","model-context-protocol","python","reverse-engineering","windows"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bethington.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-31T00:02:34.000Z","updated_at":"2026-01-29T07:47:47.000Z","dependencies_parsed_at":"2025-08-07T15:16:44.930Z","dependency_job_id":null,"html_url":"https://github.com/bethington/cheat-engine-server-python","commit_stats":null,"previous_names":["bethington/cheat-engine-server-python"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/bethington/cheat-engine-server-python","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bethington%2Fcheat-engine-server-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bethington%2Fcheat-engine-server-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bethington%2Fcheat-engine-server-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bethington%2Fcheat-engine-server-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bethington","download_url":"https://codeload.github.com/bethington/cheat-engine-server-python/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bethington%2Fcheat-engine-server-python/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33412083,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T18:09:33.147Z","status":"ssl_error","status_checked_at":"2026-05-23T18:09:31.380Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cheat-engine","debugging","mcp","memory-analysis","model-context-protocol","python","reverse-engineering","windows"],"created_at":"2026-05-23T21:04:28.939Z","updated_at":"2026-05-23T21:04:38.180Z","avatar_url":"https://github.com/bethington.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCP Cheat Engine Server Documentation\r\n\n\u003e If you find this useful, please ⭐ star the repo — it helps others discover it!\n\r\n## 📋 Table of Contents\r\n\r\n1. [Overview](#overview)\r\n2. [Quick Start Guide](#quick-start-guide)\r\n3. [Installation](#installation)\r\n4. [Configuration](#configuration)\r\n5. [Using the Tools](#using-the-tools)\r\n6. [Safety \u0026 Security](#safety--security)\r\n7. [Troubleshooting](#troubleshooting)\r\n8. [Advanced Usage](#advanced-usage)\r\n9. [API Reference](#api-reference)\r\n10. [FAQ](#faq)\r\n\r\n---\r\n\r\n## 🎯 Overview\r\n\r\nThe **MCP Cheat Engine Server** provides safe, structured access to memory analysis and debugging functionality through the Model Context Protocol (MCP). This tool is designed for:\r\n\r\n- **Software developers** debugging applications\r\n- **Security researchers** analyzing programs\r\n- **Students** learning about computer memory and reverse engineering\r\n- **Game modders** understanding game mechanics\r\n\r\n### ⚠️ Important Safety Notice\r\nThis server operates in **READ-ONLY mode** for safety. It can read and analyze memory but cannot modify it. All operations are logged for security auditing.\r\n\r\n### 🔧 Key Features\r\n- ✅ Process enumeration and attachment\r\n- ✅ Memory reading with multiple data types\r\n- ✅ Pattern scanning and searching\r\n- ✅ Assembly code disassembly\r\n- ✅ Pointer chain resolution\r\n- ✅ Cheat Engine table (.CT) import\r\n- ✅ Safe Lua script analysis\r\n- ✅ Comprehensive security controls\r\n\r\n---\r\n\r\n## 🚀 Quick Start Guide\r\n\r\n### Prerequisites\r\n- **Windows 10/11** (64-bit recommended)\r\n- **Python 3.9 or higher**\r\n- **Administrator privileges** (for memory access)\r\n- **Claude Desktop** or compatible MCP client\r\n\r\n### 30-Second Setup\r\n1. **Download** the server files to your computer\r\n2. **Open PowerShell as Administrator**\r\n3. **Navigate** to the server directory\r\n4. **Install dependencies**: `pip install -r requirements.txt`\r\n5. **Start the server**: `python server/main.py`\r\n\r\n### First Use\r\n1. **List processes**: Use the `list_processes` tool to see available programs\r\n2. **Attach to a process**: Use `attach_to_process` with a process ID\r\n3. **Read memory**: Use `read_memory_region` to examine memory\r\n4. **Detach safely**: Use `detach_from_process` when done\r\n\r\n### 🔌 Claude Desktop MCP Setup\r\n\r\n**📖 For detailed Claude Desktop setup instructions, see [MCP_SETUP.md](MCP_SETUP.md)**\r\n\r\nQuick configuration summary:\r\n1. **Find your Claude Desktop config**: `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows)\r\n2. **Add the MCP server configuration**:\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"cheat-engine\": {\r\n      \"command\": \"python\",\r\n      \"args\": [\"path\\\\to\\\\server\\\\main.py\", \"--debug\", \"--read-only\"],\r\n      \"cwd\": \"path\\\\to\\\\cheat-engine-server-python\"\r\n    }\r\n  }\r\n}\r\n```\r\n3. **Restart Claude Desktop**\r\n4. **Test**: Ask Claude to \"list processes using the MCP server\"\r\n\r\n---\r\n\r\n## 📦 Installation\r\n\r\n### Step 1: System Requirements\r\n- **Operating System**: Windows 10/11 (Primary), Linux/macOS (Limited)\r\n- **Python Version**: 3.9, 3.10, 3.11, or 3.12\r\n- **Memory**: 4GB RAM minimum, 8GB recommended\r\n- **Permissions**: Administrator/root access required\r\n\r\n### Step 2: Download and Setup\r\n```powershell\r\n# Clone or download the project\r\ncd C:\\your-desired-location\r\n# Extract files if downloaded as ZIP\r\n\r\n# Navigate to project directory\r\ncd cheat-engine-server-python\r\n\r\n# Verify Python version\r\npython --version\r\n```\r\n\r\n### Step 3: Install Dependencies\r\n```powershell\r\n# Install required packages\r\npip install -r requirements.txt\r\n\r\n# Verify installation\r\npython -c \"import mcp, trio, psutil, capstone; print('All dependencies installed successfully!')\"\r\n```\r\n\r\n### Step 4: Test Installation\r\n```powershell\r\n# Test the server\r\npython server/main.py --test\r\n\r\n# You should see: \"MCP Cheat Engine Server initialized successfully\"\r\n```\r\n\r\n---\r\n\r\n## ⚙️ Configuration\r\n\r\n### Basic Configuration\r\nThe server uses configuration files in the `server/config/` directory:\r\n\r\n#### `settings.json` (Auto-created on first run)\r\n```json\r\n{\r\n  \"security\": {\r\n    \"read_only_mode\": true,\r\n    \"require_whitelist\": true,\r\n    \"log_all_operations\": true\r\n  },\r\n  \"performance\": {\r\n    \"max_memory_read\": 1048576,\r\n    \"scan_timeout\": 30,\r\n    \"max_results\": 1000\r\n  }\r\n}\r\n```\r\n\r\n#### `whitelist.json` (Process Access Control)\r\n```json\r\n{\r\n  \"processes\": [\r\n    {\r\n      \"name\": \"notepad.exe\",\r\n      \"allowed\": true,\r\n      \"description\": \"Text editor for testing\"\r\n    },\r\n    {\r\n      \"name\": \"calculator.exe\", \r\n      \"allowed\": true,\r\n      \"description\": \"Calculator application\"\r\n    }\r\n  ]\r\n}\r\n```\r\n\r\n### Security Settings Explained\r\n\r\n| Setting | Description | Default | Recommendation |\r\n|---------|-------------|---------|----------------|\r\n| `read_only_mode` | Prevents memory writing | `true` | Keep enabled |\r\n| `require_whitelist` | Only allow whitelisted processes | `true` | Enable for safety |\r\n| `log_all_operations` | Log every operation | `true` | Enable for auditing |\r\n| `max_memory_read` | Maximum bytes per read | 1MB | Adjust as needed |\r\n\r\n---\r\n\r\n## 🛠️ Using the Tools\r\n\r\n### 1. Process Management\r\n\r\n#### List Available Processes\r\n```python\r\n# Find processes you can attach to\r\nresult = use_tool(\"list_processes\")\r\n```\r\n**What you'll see:**\r\n- Process name and ID\r\n- Memory usage\r\n- Whether it's accessible\r\n- Security level required\r\n\r\n#### Attach to a Process\r\n```python\r\n# Attach to a specific process\r\nresult = use_tool(\"attach_to_process\", {\r\n    \"process_id\": 1234\r\n})\r\n```\r\n**Best practices:**\r\n- Start with simple programs like Notepad\r\n- Always detach when finished\r\n- Check the whitelist if attachment fails\r\n\r\n### 2. Memory Reading\r\n\r\n#### Read Memory at Address\r\n```python\r\n# Read 64 bytes starting at address 0x140000000\r\nresult = use_tool(\"read_memory_region\", {\r\n    \"address\": \"0x140000000\",\r\n    \"size\": 64,\r\n    \"data_type\": \"bytes\"\r\n})\r\n```\r\n\r\n#### Supported Data Types\r\n- `bytes` - Raw byte data\r\n- `string` - ASCII/UTF-8 text\r\n- `int32` - 32-bit signed integer\r\n- `uint32` - 32-bit unsigned integer\r\n- `int64` - 64-bit signed integer\r\n- `uint64` - 64-bit unsigned integer\r\n- `float` - 32-bit floating point\r\n- `double` - 64-bit floating point\r\n\r\n### 3. Memory Scanning\r\n\r\n#### Search for Patterns\r\n```python\r\n# Find all occurrences of a byte pattern\r\nresult = use_tool(\"scan_memory\", {\r\n    \"pattern\": \"48 8B 05 ?? ?? ?? ??\",  # ?? = wildcard\r\n    \"start_address\": \"0x140000000\",\r\n    \"end_address\": \"0x141000000\"\r\n})\r\n```\r\n\r\n#### Pattern Format Examples\r\n- `\"41 42 43\"` - Find bytes 0x41, 0x42, 0x43\r\n- `\"48 ?? 05 ?? ?? ?? ??\"` - Wildcards for unknown bytes\r\n- `\"Hello World\"` - Search for ASCII text\r\n- `\"00 00 00 01\"` - Find integer value 1\r\n\r\n### 4. Code Analysis\r\n\r\n#### Disassemble Assembly Code\r\n```python\r\n# Disassemble 100 bytes of code\r\nresult = use_tool(\"disassemble_code\", {\r\n    \"address\": \"0x140001000\",\r\n    \"size\": 100,\r\n    \"architecture\": \"x64\"\r\n})\r\n```\r\n\r\n#### Analyze Data Structures\r\n```python\r\n# Analyze memory for data structures\r\nresult = use_tool(\"analyze_structure\", {\r\n    \"address\": \"0x200000000\",\r\n    \"size\": 256\r\n})\r\n```\r\n\r\n### 5. Pointer Chains\r\n\r\n#### Follow Multi-Level Pointers\r\n```python\r\n# Resolve [[base + 0x10] + 0x20] + 0x30\r\nresult = use_tool(\"resolve_pointer_chain\", {\r\n    \"base_address\": \"0x140000000\",\r\n    \"offsets\": [16, 32, 48]  # 0x10, 0x20, 0x30 in decimal\r\n})\r\n```\r\n\r\n---\r\n\r\n## 🔒 Safety \u0026 Security\r\n\r\n### Read-Only Protection\r\nThe server **cannot modify memory** - it can only read and analyze. This prevents:\r\n- Accidental program crashes\r\n- Security vulnerabilities\r\n- System instability\r\n\r\n### Process Whitelist\r\nOnly approved processes can be accessed:\r\n```json\r\n{\r\n  \"processes\": [\r\n    {\"name\": \"notepad.exe\", \"allowed\": true},\r\n    {\"name\": \"suspicious.exe\", \"allowed\": false}\r\n  ]\r\n}\r\n```\r\n\r\n### Operation Logging\r\nAll operations are logged to `logs/operations.log`:\r\n```\r\n2025-07-30 10:30:15 - INFO - Process attached: notepad.exe (PID: 1234)\r\n2025-07-30 10:30:20 - INFO - Memory read: 0x140000000, size: 64\r\n2025-07-30 10:30:25 - INFO - Process detached: notepad.exe\r\n```\r\n\r\n### Permission Requirements\r\n- **Windows**: Run as Administrator\r\n- **Linux**: Run as root or with appropriate capabilities\r\n- **macOS**: May require disabling SIP for some operations\r\n\r\n---\r\n\r\n## 🔧 Troubleshooting\r\n\r\n### Common Issues\r\n\r\n#### \"Access Denied\" Error\r\n**Problem**: Cannot attach to process\r\n**Solutions**:\r\n1. Run as Administrator\r\n2. Check if process is in whitelist\r\n3. Verify process is not protected by anti-virus\r\n\r\n#### \"Module Not Found\" Error\r\n**Problem**: Python dependencies missing\r\n**Solution**:\r\n```powershell\r\npip install --upgrade -r requirements.txt\r\n```\r\n\r\n#### \"Process Not Found\" Error\r\n**Problem**: Process ID doesn't exist\r\n**Solutions**:\r\n1. Use `list_processes` to get current IDs\r\n2. Check if process is still running\r\n3. Try process name instead of ID\r\n\r\n#### Memory Read Fails\r\n**Problem**: Cannot read memory at address\r\n**Solutions**:\r\n1. Check if address is valid with `get_memory_regions`\r\n2. Verify memory protection allows reading\r\n3. Try smaller read size\r\n\r\n### Debug Mode\r\nEnable detailed logging:\r\n```powershell\r\npython server/main.py --debug\r\n```\r\n\r\n### Getting Help\r\n1. Check the FAQ section below\r\n2. Review log files in `logs/` directory\r\n3. Verify configuration in `server/config/`\r\n4. Test with simple programs like Notepad first\r\n\r\n---\r\n\r\n## 🎓 Advanced Usage\r\n\r\n### Cheat Engine Table Import\r\nImport existing .CT files:\r\n```python\r\nresult = use_tool(\"import_cheat_table\", {\r\n    \"file_path\": \"C:/path/to/table.CT\"\r\n})\r\n```\r\n\r\n### Lua Script Analysis\r\nAnalyze Cheat Engine Lua scripts:\r\n```python\r\nresult = use_tool(\"execute_lua_script\", {\r\n    \"script_content\": \"print('Hello from Lua')\",\r\n    \"safe_mode\": true\r\n})\r\n```\r\n\r\n### Custom Memory Regions\r\nDefine specific regions for analysis:\r\n```python\r\n# Get full memory map\r\nregions = use_tool(\"get_memory_regions\")\r\n\r\n# Analyze specific region\r\nfor region in regions:\r\n    if region['protect'] == 'PAGE_EXECUTE_READ':\r\n        # Analyze executable memory\r\n        pass\r\n```\r\n\r\n### Automation Examples\r\n```python\r\n# Complete analysis workflow\r\ndef analyze_process(process_name):\r\n    # 1. Find and attach to process\r\n    processes = use_tool(\"list_processes\")\r\n    target_pid = find_process_by_name(processes, process_name)\r\n    \r\n    # 2. Attach to process\r\n    use_tool(\"attach_to_process\", {\"process_id\": target_pid})\r\n    \r\n    # 3. Get memory layout\r\n    regions = use_tool(\"get_memory_regions\")\r\n    \r\n    # 4. Scan for patterns\r\n    for region in regions:\r\n        if region['readable']:\r\n            scan_results = use_tool(\"scan_memory\", {\r\n                \"pattern\": \"48 8B 05\",\r\n                \"start_address\": region['base_address'],\r\n                \"end_address\": region['base_address'] + region['size']\r\n            })\r\n    \r\n    # 5. Clean up\r\n    use_tool(\"detach_from_process\")\r\n```\r\n\r\n---\r\n\r\n## 📚 API Reference\r\n\r\n### Tool Categories\r\n\r\n#### Process Management\r\n- **list_processes()** - Get all running processes\r\n- **attach_to_process(process_id)** - Attach to specific process\r\n- **detach_from_process()** - Safely detach from current process\r\n- **get_process_info()** - Get detailed process information\r\n\r\n#### Memory Operations  \r\n- **read_memory_region(address, size, data_type)** - Read memory\r\n- **get_memory_regions()** - Get virtual memory layout\r\n- **scan_memory(pattern, start_address, end_address)** - Pattern search\r\n\r\n#### Analysis Tools\r\n- **analyze_structure(address, size)** - Structure analysis\r\n- **disassemble_code(address, size, architecture)** - Code disassembly\r\n- **resolve_pointer_chain(base_address, offsets)** - Pointer resolution\r\n\r\n#### Advanced Features\r\n- **import_cheat_table(file_path)** - Import .CT files\r\n- **execute_lua_script(script_content, safe_mode)** - Lua analysis\r\n\r\n### Data Types Reference\r\n\r\n| Type | Size | Range | Use Case |\r\n|------|------|-------|----------|\r\n| `int8` | 1 byte | -128 to 127 | Small signed numbers |\r\n| `uint8` | 1 byte | 0 to 255 | Bytes, characters |\r\n| `int16` | 2 bytes | -32,768 to 32,767 | Short integers |\r\n| `uint16` | 2 bytes | 0 to 65,535 | Port numbers |\r\n| `int32` | 4 bytes | ±2.1 billion | Standard integers |\r\n| `uint32` | 4 bytes | 0 to 4.2 billion | Addresses (32-bit) |\r\n| `int64` | 8 bytes | ±9.2 quintillion | Large numbers |\r\n| `uint64` | 8 bytes | 0 to 18.4 quintillion | Addresses (64-bit) |\r\n| `float` | 4 bytes | ±3.4E±38 | Decimal numbers |\r\n| `double` | 8 bytes | ±1.7E±308 | High precision decimals |\r\n\r\n---\r\n\r\n## ❓ FAQ\r\n\r\n### General Questions\r\n\r\n**Q: Is this tool safe to use?**\r\nA: Yes, the server operates in read-only mode and cannot modify memory or harm your system.\r\n\r\n**Q: Can I use this on games?**\r\nA: Yes, but respect the terms of service of online games. This tool is primarily for educational and debugging purposes.\r\n\r\n**Q: Do I need Cheat Engine installed?**\r\nA: No, this is a standalone server that provides similar functionality through MCP.\r\n\r\n### Technical Questions\r\n\r\n**Q: Why do I need Administrator privileges?**\r\nA: Windows requires elevated privileges to read memory from other processes for security reasons.\r\n\r\n**Q: Can I run this on Mac or Linux?**\r\nA: The server has limited support for Mac/Linux. Some Windows-specific features may not work.\r\n\r\n**Q: How much memory does the server use?**\r\nA: Typically 50-100MB, depending on the size of processes being analyzed.\r\n\r\n### Usage Questions\r\n\r\n**Q: What processes should I start with?**\r\nA: Begin with simple programs like Notepad, Calculator, or your own test applications.\r\n\r\n**Q: How do I find the right memory addresses?**\r\nA: Use memory scanning to find patterns, then analyze the results to identify relevant addresses.\r\n\r\n**Q: Can I save my analysis results?**\r\nA: Yes, all tool results can be saved to files for later reference and analysis.\r\n\r\n### Troubleshooting Questions\r\n\r\n**Q: The server won't start - what should I check?**\r\nA: Verify Python version (3.9+), install dependencies, and run as Administrator.\r\n\r\n**Q: I can't attach to a process - why?**\r\nA: Check the process whitelist, verify the process is running, and ensure you have Administrator privileges.\r\n\r\n**Q: Memory reads are failing - what's wrong?**\r\nA: The memory address may be invalid or protected. Use `get_memory_regions` to find readable areas.\r\n\r\n---\r\n\r\n## 📝 License \u0026 Credits\r\n\r\nThis project is licensed under the MIT License. Built with:\r\n- **FastMCP** - Model Context Protocol implementation\r\n- **Capstone** - Disassembly engine\r\n- **psutil** - Process and system utilities\r\n- **trio** - Async I/O framework\r\n\r\n---\r\n\r\n## 📞 Support\r\n\r\nFor additional help:\r\n1. Review this documentation thoroughly\r\n2. Check the troubleshooting section\r\n3. Enable debug mode for detailed error information\r\n4. Test with simple programs first\r\n\r\nRemember: This tool is for educational and legitimate debugging purposes. Always respect software licenses and terms of service.\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbethington%2Fcheat-engine-server-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbethington%2Fcheat-engine-server-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbethington%2Fcheat-engine-server-python/lists"}