bethington/cheat-engine-server-python

이 프로젝트가 유용하다고 생각하신다면 ⭐ star를 눌러주세요 — 다른 사람들이 발견하는 데 큰 도움이 됩니다!

• 개요 (Overview)
• 빠른 시작 가이드 (Quick Start Guide)
• 설치 (Installation)
• 설정 (Configuration)
• 도구 사용법 (Using the Tools)
• 안전 및 보안 (Safety & Security)
• 문제 해결 (Troubleshooting)
• 고급 사용법 (Advanced Usage)
• API 레퍼런스 (API Reference)
• 자주 묻는 질문 (FAQ)

MCP Cheat Engine Server는 Model Context Protocol (MCP)을 통해 메모리 분석 및 디버깅 기능에 대한 안전하고 구조화된 접근을 제공합니다. 이 도구는 다음과 같은 사용자를 위해 설계되었습니다:

소프트웨어 개발자 (Software developers): 애플리케이션 디버깅
보안 연구원 (Security researchers): 프로그램 분석
학생 (Students): 컴퓨터 메모리 및 리버스 엔지니어링 (Reverse Engineering) 학습
게임 모더 (Game modders): 게임 메커니즘 이해

이 서버는 안전을 위해 **읽기 전용 모드 (READ-ONLY mode)**로 작동합니다. 메모리를 읽고 분석할 수는 있지만 수정할 수는 없습니다. 모든 작업은 보안 감사를 위해 로그로 기록됩니다.

• ✅ 프로세스 열거 및 연결 (Process enumeration and attachment)
• ✅ 다양한 데이터 타입을 사용한 메모리 읽기 (Memory reading)
• ✅ 패턴 스캐닝 및 검색 (Pattern scanning and searching)
• ✅ 어셈블리 코드 역어셈블 (Assembly code disassembly)
• ✅ 포인터 체인 해석 (Pointer chain resolution)
• ✅ Cheat Engine 테이블 (.CT) 가져오기
• ✅ 안전한 Lua 스크립트 분석
• ✅ 포괄적인 보안 제어

Windows 10/11 (64비트 권장)
Python 3.9 이상
관리자 권한 (메모리 접근용)
Claude Desktop 또는 호환 가능한 MCP 클라이언트

서버 파일 다운로드: 서버 파일을 컴퓨터로 다운로드합니다.
PowerShell을 관리자 권한으로 실행: PowerShell을 관리자 권한으로 엽니다.
디렉토리 이동: 서버 디렉토리로 이동합니다.
의존성 설치: pip install -r requirements.txt 명령어를 실행합니다.

서버 시작: python server/main.py 명령어를 실행합니다.

프로세스 목록 확인: list_processes 도구를 사용하여 사용 가능한 프로그램을 확인합니다.
프로세스에 연결: 프로세스 ID와 함께 attach_to_process를 사용합니다.
메모리 읽기: read_memory_region을 사용하여 메모리를 조사합니다.
안전하게 연결 해제: 작업이 완료되면 detach_from_process를 사용합니다.

📖 Claude Desktop 설정에 대한 자세한 지침은 MCP_SETUP.md를 참조하세요.

빠른 설정 요약:

Claude Desktop 설정 파일 찾기: %APPDATA%\Claude\claude_desktop_config.json (Windows)
MCP 서버 설정 추가:

{
"mcpServers": {
"cheat-engine": {
...

Claude Desktop 재시작

테스트: Claude에게 "MCP 서버를 사용하는 프로세스 목록을 나열해줘"라고 요청하세요.

운영 체제 (Operating System): Windows 10/11 (주요 지원), Linux/macOS (제한적 지원)
Python 버전: 3.9, 3.10, 3.11 또는 3.12
메모리: 최소 4GB RAM, 8GB 권장
권한: 관리자(Administrator)/root 권한 필요

# 프로젝트를 클론(Clone)하거나 다운로드합니다
cd C:\your-desired-location
# ZIP 파일로 다운로드한 경우 파일 압축을 해제합니다
...

# 필수 패키지를 설치합니다
pip install -r requirements.txt
# 설치를 확인합니다
...

# 서버를 테스트합니다
python server/main.py --test
# 다음과 같은 메시지가 표시되어야 합니다: "MCP Cheat Engine Server initialized successfully"

서버는 server/config/ 디렉토리 내의 설정 파일을 사용합니다:

{
"security": {
"read_only_mode": true,
...

{
"processes": [
{
...

설정 (Setting)	설명 (Description)	기본값 (Default)	권장 사항 (Recommendation)
read_only_mode	메모리 쓰기 방지	true	활성화 상태 유지
require_whitelist	화이트리스트에 등록된 프로세스만 허용	true	안전을 위해 활성화
log_all_operations	모든 작업 로그 기록	true	감사를 위해 활성화
max_memory_read	읽기당 최대 바이트 수	1MB	필요에 따라 조정

# 연결 가능한 프로세스를 찾습니다
result = use_tool("list_processes")

확인 가능한 내용:

• 프로세스 이름 및 ID
• 메모리 사용량
• 접근 가능 여부
• 요구되는 보안 수준

# 특정 프로세스에 연결(Attach)합니다
result = use_tool("attach_to_process", {
"process_id": 1234
...

모범 사례 (Best practices):

• 메모장(Notepad)과 같은 간단한 프로그램으로 시작하세요
• 작업이 끝나면 항상 연결을 해제(Detach)하세요
• 연결에 실패하면 화이트리스트를 확인하세요

# 0x140000000 주소부터 64바이트를 읽습니다
result = use_tool("read_memory_region", {
"address": "0x140000000",
...

bytes

• 원시 바이트 데이터

string

• ASCII/UTF-8 텍스트

int32

• 32비트 부호 있는 정수 (signed integer)

uint32

• 32비트 부호 없는 정수 (unsigned integer)

int64

• 64비트 부호 있는 정수 (signed integer)

uint64

• 64비트 부호 없는 정수 (unsigned integer)

float

• 32비트 부동 소수점 (floating point)

double

• 64비트 부동 소수점 (floating point)

# 바이트 패턴의 모든 발생 사례 찾기
result = use_tool("scan_memory", {
"pattern": "48 8B 05 ?? ?? ?? ??", # ?? = 와일드카드 (wildcard)
...

"41 42 43"

• 0x41, 0x42, 0x43 바이트 찾기

"48 ?? 05 ?? ?? ?? ??"

• 알 수 없는 바이트를 위한 와일드카드 (wildcards)

"Hello World"

• ASCII 텍스트 검색

"00 00 00 01"

• 정수 값 1 찾기

# 코드 100바이트 역어셈블 (Disassemble)
result = use_tool("disassemble_code", {
"address": "0x140001000",
...

# 데이터 구조를 위해 메모리 분석
result = use_tool("analyze_structure", {
"address": "0x200000000",
...

# [[base + 0x10] + 0x20] + 0x30 포인터 체인 해석 (Resolve)
result = use_tool("resolve_pointer_chain", {
"base_address": "0x140000000",
...

서버는 메모리를 수정할 수 없으며 — 오직 읽기 및 분석만 가능합니다. 이는 다음을 방지합니다:

• 우발적인 프로그램 충돌 (crashes)
• 보안 취약점 (security vulnerabilities)
• 시스템 불안정성 (instability)

승인된 프로세스만 접근할 수 있습니다:

{
"processes": [
{"name": "notepad.exe", "allowed": true},
...

모든 작업은 logs/operations.log에 기록됩니다:

2025-07-30 10:30:15 - INFO - Process attached: notepad.exe (PID: 1234)
2025-07-30 10:30:20 - INFO - Memory read: 0x140000000, size: 64
2025-07-30 10:30:25 - INFO - Process detached: notepad.exe

Windows: 관리자 권한 (Administrator)으로 실행
Linux: root 또는 적절한 권한 (capabilities)으로 실행
macOS: 일부 작업의 경우 SIP 비활성화가 필요할 수 있음

문제: 프로세스에 연결(attach)할 수 없음
해결 방법:

• 관리자 권한으로 실행
• 프로세스가 화이트리스트(whitelist)에 있는지 확인
• 프로세스가 안티바이러스(anti-virus)에 의해 보호되고 있지 않은지 확인

문제: Python 의존성(dependencies) 누락
해결 방법:

pip install --upgrade -r requirements.txt

문제: 프로세스 ID(PID)가 존재하지 않음
해결 방법:

• list_processes를 사용하여 현재 ID를 가져오기
• 프로세스가 여전히 실행 중인지 확인
• ID 대신 프로세스 이름 사용 시도

문제: 해당 주소의 메모리를 읽을 수 없음
해결 방법:

• get_memory_regions로 주소가 유효한지 확인
• 메모리 보호(memory protection) 설정이 읽기를 허용하는지 확인
• 더 작은 읽기 크기(read size) 시도

상세 로깅(detailed logging) 활성화:

python server/main.py --debug

• 아래의 FAQ 섹션을 확인하세요

• logs/ 디렉토리 내의 로그 파일을 검토하세요

• server/config/ 내의 설정을 확인하세요

• 먼저 Notepad와 같은 간단한 프로그램으로 테스트하세요

기존 .CT 파일 가져오기:

result = use_tool("import_cheat_table", {
"file_path": "C:/path/to/table.CT"
})

Cheat Engine Lua 스크립트 분석:

result = use_tool("execute_lua_script", {
"script_content": "print('Hello from Lua')",
"safe_mode": true
...

분석을 위한 특정 영역 정의:

# 전체 메모리 맵(memory map) 가져오기
regions = use_tool("get_memory_regions")
# 특정 영역 분석
...

# 전체 분석 워크플로우(workflow)
def analyze_process(process_name):
# 1. 프로세스 찾기 및 연결(attach)
...

list_processes()- 모든 실행 중인 프로세스 가져오기
attach_to_process(process_id)- 특정 프로세스에 연결(attach)
detach_from_process()- 현재 프로세스에서 안전하게 연결 해제(detach)
get_process_info()- 상세한 프로세스 정보 가져오기

read_memory_region(address, size, data_type)- 메모리 읽기
get_memory_regions()- 가상 메모리 레이아웃(virtual memory layout) 가져오기
scan_memory(pattern, start_address, end_address)- 패턴 검색(pattern search)

analyze_structure(address, size)- 구조 분석(structure analysis)
disassemble_code(address, size, architecture)- 코드 역어셈블(code disassembly)
resolve_pointer_chain(base_address, offsets)- 포인터 해석(pointer resolution)

import_cheat_table(file_path)-.CT 파일 가져오기
execute_lua_script(script_content, safe_mode)- Lua 분석

유형	크기	범위	사용 사례
int8	1 byte	-128 ~ 127	작은 부호 있는 숫자 (Small signed numbers)
uint8	1 byte	0 ~ 255	바이트 (Bytes), 문자 (characters)
int16	2 bytes	-32,768 ~ 32,767	짧은 정수 (Short integers)
uint16	2 bytes	0 ~ 65,535	포트 번호 (Port numbers)
int32	4 bytes	±21억	표준 정수 (Standard integers)
uint32	4 bytes	0 ~ 42억	주소 (Addresses) (32-bit)
int64	8 bytes	±9.2 quintillion	큰 숫자 (Large numbers)
uint64	8 bytes	0 ~ 18.4 quintillion	주소 (Addresses) (64-bit)
float	4 bytes	±3.4E±38	소수 (Decimal numbers)
double	8 bytes	±1.7E±308	고정밀 소수 (High precision decimals)

Q: 이 도구는 사용하기 안전한가요?
A: 네, 서버는 읽기 전용 (read-only) 모드로 작동하며 메모리를 수정하거나 시스템에 해를 끼칠 수 없습니다.

Q: 게임에서 사용할 수 있나요?
A: 네, 하지만 온라인 게임의 서비스 약관 (terms of service)을 준수하십시오. 이 도구는 주로 교육 및 디버깅 (debugging) 목적으로 설계되었습니다.

Q: Cheat Engine이 설치되어 있어야 하나요?
A: 아니요, 이것은 MCP를 통해 유사한 기능을 제공하는 독립형 (standalone) 서버입니다.

Q: 왜 관리자 권한 (Administrator privileges)이 필요한가요?
A: Windows는 보안상의 이유로 다른 프로세스의 메모리를 읽기 위해 승격된 권한을 요구합니다.

Q: Mac이나 Linux에서도 실행할 수 있나요?
A: 서버는 Mac/Linux에 대해 제한적인 지원을 제공합니다. 일부 Windows 전용 기능은 작동하지 않을 수 있습니다.

Q: 서버가 메모리를 얼마나 사용하나요?
A: 일반적으로 분석 중인 프로세스의 크기에 따라 50-100MB를 사용합니다.

Q: 어떤 프로세스로 시작하는 것이 좋을까요?
A: 메모장 (Notepad), 계산기 (Calculator) 또는 직접 만든 테스트 애플리케이션과 같은 간단한 프로그램으로 시작하십시오.

Q: 올바른 메모리 주소를 어떻게 찾나요?
A: 메모리 스캐닝 (memory scanning)을 사용하여 패턴을 찾은 다음, 결과를 분석하여 관련 주소를 식별하십시오.

Q: 분석 결과를 저장할 수 있나요?
A: 네, 모든 도구 결과는 나중에 참조 및 분석할 수 있도록 파일로 저장할 수 있습니다.

Q: 서버가 시작되지 않습니다 - 무엇을 확인해야 하나요?
A: Python 버전 (3.9 이상)을 확인하고, 종속성 (dependencies)을 설치한 후, 관리자 권한으로 실행하십시오.

Q: 프로세스에 연결(attach)할 수 없습니다 - 이유가 무엇인가요?
A: 프로세스 화이트리스트 (whitelist)를 확인하고, 프로세스가 실행 중인지 확인하며, 관리자 권한 (Administrator privileges)을 보유하고 있는지 확인하십시오.

Q: 메모리 읽기 (Memory reads)가 실패합니다 - 무엇이 문제인가요?
A: 메모리 주소 (memory address)가 유효하지 않거나 보호되어 있을 수 있습니다. 읽기 가능한 영역을 찾으려면 get_memory_regions를 사용하십시오.

이 프로젝트는 MIT 라이선스 (MIT License) 하에 라이선스가 부여됩니다. 다음을 사용하여 구축되었습니다:

FastMCP- Model Context Protocol 구현
Capstone- 역어셈블리 엔진 (Disassembly engine)
psutil- 프로세스 및 시스템 유틸리티 (Process and system utilities)
trio- 비동기 I/O 프레임워크 (Async I/O framework)

추가적인 도움이 필요한 경우:

• 이 문서를 철저히 검토하십시오
• 문제 해결 (troubleshooting) 섹션을 확인하십시오
• 상세한 오류 정보를 위해 디버그 모드 (debug mode)를 활성화하십시오
• 먼저 간단한 프로그램으로 테스트하십시오

주의사항: 이 도구는 교육 및 정당한 디버깅 목적으로만 사용되어야 합니다. 항상 소프트웨어 라이선스 및 서비스 약관을 준수하십시오.