Content
# samp-executor-mcp
> MCP server connecting AI clients (Claude Code, Cursor, Codex, OpenCode, Antigravity, Kiro, Gemini CLI, Qwen CLI, Factory Droid, Windsurf, Devin) to a live **SA-MP 0.3.7 R3** client via Moonloader. Fork of [notpoiu/roblox-executor-mcp](https://github.com/notpoiu/roblox-executor-mcp), rewritten from Roblox to SAMP.
## 📖 Table of Contents
1. [What is this and why](#-what-is-this-and-why)
2. [Architecture (how everything is connected)](#-architecture-how-everything-is-connected)
3. [What lies where](#-what-lies-where)
4. [Requirements](#-requirements)
5. [Installation in 4 steps](#-installation-in-4-steps)
6. [How to check if it works](#-how-to-check-if-it-works)
7. [List of MCP tools (40 items)](#-list-of-mcp-tools-40-items)
8. [Usage examples](#-usage-examples)
9. [Landing site](#-landing-site)
10. [HTTP API (for external scripts)](#-http-api-for-external-scripts)
11. [Troubleshooting](#-troubleshooting)
12. [Security and anti-cheat](#-security-and-anti-cheat)
13. [Differences from the original roblox-executor-mcp](#-differences-from-the-original-roblox-executor-mcp)
14. [License and credits](#-license-and-credits)
## 🎯 What is this and why
Allows AI (Claude, GPT, Gemini, etc.) to **see and control** your SAMP client in real-time:
- Read position, HP, armor, money, weapon, vehicle
- See nearby players and NPCs with their speeds and directions
- Spy on RPC packets (incoming/outgoing) — what the server sends and what you send
- Read and write directly to game memory (CPed, CVehicle, CObject structures)
- Respond to dialogs, send chat, press keys
- **Write Lua scripts and inject them into Moonloader immediately** — AI writes code, saves, tests, iterates
- Take screenshots of the game window
- Grep the source code of your .lua scripts
**Why is this needed:**
- 🛠 Development and debugging of your Moonloader scripts with AI assistance
- 🔍 Reverse engineering of server RPC protocols
- 🤖 Creating bots/macros (with caution — see security section)
- 📚 Studying the memory structure of SAMP 0.3.7 R3
## 🏗 Architecture (how everything is connected)
```
┌──────────────────────┐ stdio (JSON-RPC) ┌─────────────────────────────┐
│ AI Client │◀──────────────────────▶│ MCP Server (Node.js + TS) │
│ Claude Code / │ │ src/index.ts │
│ Cursor / Codex / │ │ ├ 40 MCP tools │
│ Gemini CLI / etc. │ │ └ HTTP+WS bridge :16385 │
└──────────────────────┘ │ │
│ Also serves: │
│ ├ Landing site (/) │
│ ├ Static assets (/assets/) │
│ └ REST API (/api/*) │
└─────────────┬───────────────┘
│
│ WebSocket
│ ws://127.0.0.1:16385
▼
┌─────────────────────────────────────────┐
│ connector.lua (in Moonloader) │
│ ├ Registers on load │
│ ├ Receives commands, executes, responds│
│ ├ sampev hooks — RPC spy + event log │
│ ├ memory.read/write — direct memory │
│ ├ loadstring() — auto-injector scripts│
│ └ print() capture — output tracking │
└────────────────────┬────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ GTA SA + SAMP 0.3.7 R3 │
│ (gta_sa.exe — one or multiple windows) │
└─────────────────────────────────────────┘
```
**Key points:**
1. MCP server communicates with AI client via stdio (MCP standard)
2. MCP server holds HTTP+WS server on port **16385**
3. Lua connector in Moonloader connects to this port via WebSocket
4. Each MCP tool call → command to connector → response back
5. Landing site and REST API available on the same port 16385
## 📁 File Structure
```
samp-executor-mcp/
│
├── 📦 package.json # npm dependencies and scripts
├── 📦 tsconfig.json # TypeScript config
├── 📦 .gitignore # git exceptions (node_modules, dist)
├── 📄 README.md # this file
│
├── 📁 src/ # MCP SERVER SOURCES (TypeScript)
│ ├── index.ts # entry point: launches MCP server + bridge
│ ├── bridge/ # bridge core
│ │ ├── boot.ts # HTTP+WS server launch
│ │ ├── types.ts # types (SAMPClient, SAMPResponse, etc.)
│ │ └── handlers/
│ │ ├── shared/
│ │ │ ├── registry.ts # connected clients registry
│ │ │ ├── communication.ts # command sending and response waiting
│ │ │ └── script-source-store.ts
│ │ └── server/
│ │ └── primary.ts # http.createServer + WebSocketServer
│ ├── http/
│ │ ├── router.ts # automatic route detection by files
│ │ └── routes/
│ │ ├── _ws-fallback.ts # WebSocket upgrade handler
│ │ ├── index.ts # GET / — landing page
│ │ ├── assets.ts # GET /assets/* — CSS, JS, fonts
│ │ ├── script.lua.ts # GET /script.lua — connector source code
│ │ ├── health.ts # GET /health
│ │ ├── register.ts # POST /register (HTTP mode)
│ │ ├── poll.ts # GET /poll (HTTP long-poll)
│ │ ├── respond.ts # POST /respond
│ │ └── api/
│ │ ├── clients.ts # GET /api/clients
│ │ ├── install-info.ts # GET /api/install-info
│ │ └── scripts.ts # /api/scripts/* (save/get/list/inject/delete)
│ └── tools/
│ ├── factory.ts # sendAndWait, formatToolText, clientStamp
│ ├── schemas.ts # common Zod schemes
│ ├── index.ts # registerAllTools + INSTRUCTIONS for AI
│ └── impl/ # 40 files — one for each MCP tool
│
├── 📁 connector/ # LUA CONNECTOR (for Moonloader)
│ ├── connector.lua # main file: handlers + RPC spy + auto-injector
│ └── ws-client.lua # minimal WebSocket client (RFC 6455)
│ # → COPY TO: GTA SA\moonloader\
│
├── 📁 configs/ # READY CONFIGS FOR 11 AI CLIENTS
│ ├── manifest.json # list of all clients with metadata
│ ├── claude-code.txt # → .mcp.json in project root
│ ├── cursor.txt # → ~/.cursor/mcp.json
│ ├── codex.txt # → ~/.codex/config.toml
│ ├── opencode.txt # → opencode.json
│ ├── antigravity.txt # → .antigravity/mcp.json
│ ├── kiro.txt # → ~/.kiro/settings/mcp.json
│ ├── gemini-cli.txt # → ~/.gemini/settings.json
│ ├── qwen-cli.txt # → ~/.qwen/settings.json
│ ├── factory-droid.txt # → .factory/mcp.json
│ ├── windsurf.txt # → ~/.codeium/windsurf/mcp_config.json
│ └── devin.txt # → configured via Devin web interface
│
├── 📁 resources/ # REFERENCES FOR AI (read via get-resource-doc)
│ ├── samp-functions.json # ~50 SAMP/Moonloader functions with signatures
│ ├── sampev-events.md # all hookable sampev events
│ └── memory-layout.md # all SAMP 0.3.7 R3 offsets (pools, structs, globals)
│
├── 📁 templates/ # LUA SCRIPT TEMPLATES (6 pcs)
│ ├── manifest.json # template descriptions with tags
│ ├── hp-monitor.lua # simple: HP/armor/money every second
│ ├── anti-afk.lua # prevents kick for idle
│ ├── dialog-responder.lua # auto-response to dialogs by id
│ ├── server-spy.lua # passive server event logger
│ ├── esp.lua # display nearby players in chat
│ └── auto-drive.lua # auto-driving with raycast obstacle detection
│
├── 📁 scripts/ # AI WORKSPACE — scripts that AI saves
│ # (empty folder, filled via save-lua-script)
│ # DO NOT TOUCH MANUALLY — AI manages it
│
└── 📁 web/ # LANDING SITE
├── index.html # main page
└── assets/
├── css/styles.css # styles (Atlantic.vc design system)
└── js/app.js # particle canvas + live polling
```
## ✅ Requirements
| Component | Version | Where to get |
|-----------|--------|----------|
| **Windows** | 10/11 | — (only Windows, due to memory access + screenshot) |
| **Node.js** | ≥ 18 | https://nodejs.org/ |
| **GTA San Andreas** | 1.0 US (not Steam) | any clean installation |
| **SAMP** | 0.3.7 R3 | https://sa-mp.com/ |
| **Moonloader** | ≥ 0.26 | https://gtaforums.com/topic/890552-moonloader/ |
| **SAMP.Lua** | included with Moonloader | installed with Moonloader |
**Lua libraries** required for connector (included with standard Moonloader):
- `bit`, `memory`, `vkeys`, `socket`, `ffi`, `luasocket` — built-in
- `samp.samp`, `samp.raknet`, `lib.samp.events` (sampev) — from SAMP.Lua
## 🚀 Installation in 4 steps
### Step 1. Clone repository and build MCP server
```bash
git clone https://github.com/UjanJJ/samp-executor-mcp.git
cd samp-executor-mcp
npm install
npm run build
```
After this, compiled `.js` files will appear in the `dist/` folder.
> 💡 **Verification**: run `node dist/index.js` — it should output to stderr:
> ```
> [samp-mcp] bridge listening on http://127.0.0.1:16385 (ws + http)
> [samp-mcp] MCP server connected on stdio. Bridge on http://127.0.0.1:16385.
> ```
> Press Ctrl+C to stop.
### Step 2. Install Lua connector in Moonloader
Copy **two files** from repository to Moonloader folder:
```
FROM: samp-executor-mcp/connector/connector.lua
FROM: samp-executor-mcp/connector/ws-client.lua
TO: <path to GTA SA>\moonloader\connector.lua
TO: <path to GTA SA>\moonloader\ws-client.lua
```
**Example path:** `C:\Program Files\GTA San Andreas\moonloader\`
> 💡 **Alternative**: you can **not** copy files manually, but load them directly in-game via Moonloader console (`~`):
> ```lua
> loadstring(downloadFile("http://127.0.0.1:16385/script.lua"))()
> ```
> But for auto-loading on game start, it's better to copy files.
### Step 3. Connect MCP server to your AI client
Choose your AI client below and create a config:
#### Claude Code
Create a file `.mcp.json` in project root (or `~/.claude.json` for global):
```json
{
"mcpServers": {
"samp-mcp": {
"command": "node",
"args": ["C:\\full\\path\\to\\samp-executor-mcp\\dist\\index.js"]
}
}
}
```
#### Cursor
Create `~/.cursor/mcp.json` (or `.cursor/mcp.json` in project):
```json
{
"mcpServers": {
"samp-mcp": {
"command": "node",
"args": ["C:\\full\\path\\to\\samp-executor-mcp\\dist\\index.js"]
}
}
}
```
#### Codex CLI
Create `~/.codex/config.toml`:
```toml
[mcp_servers.samp-mcp]
command = "node"
args = ["C:\\full\\path\\to\\samp-executor-mcp\\dist\\index.js"]
```
#### OpenCode
Create `opencode.json` in project root:
```json
{
"mcp": {
"samp-mcp": {
"type": "local",
"command": ["node", "C:\\full\\path\\to\\samp-executor-mcp\\dist\\index.js"]
}
}
}
```
#### Antigravity / Kiro / Gemini CLI / Qwen CLI / Factory Droid / Windsurf
Ready-made snippets in [`configs/`](configs/) folder — open required `.txt` file, copy content, and paste in path specified in [`configs/manifest.json`](configs/manifest.json).
#### Devin
Configured via web interface: Settings → Tools → MCP Servers → Add. Parameters:
- Server name: `samp-mcp`
- Transport: `stdio`
- Command: `node`
- Arguments: `C:\full\path\to\samp-executor-mcp\dist\index.js`
> ⚠️ **Important**: path in `args` must be **full absolute path** to `dist/index.js`. Replace `C:\full\path\to\samp-executor-mcp\` with your actual installation path.
### Step 4. Run and verify
1. **Run MCP server** (it should work while you use AI client):
```bash
cd samp-executor-mcp
node dist/index.js
```
It should output:
```
[samp-mcp] bridge listening on http://127.0.0.1:16385
[samp-mcp] MCP server connected on stdio.
```
2. **Open landing page in browser**: http://127.0.0.1:16385/
- Landing page with hero section and particle animation should open
- In **Live Status** section, it should show "None connected" — this is normal, connector not loaded yet
3. **Run GTA SA + SAMP** (you don't need to connect to server — verification will work in menu)
4. **Connector will load automatically** on Moonloader start. On landing page in **Live Status** section, your client will appear.
5. **Open your AI client** (Claude Code, Cursor, etc.) and ask:
> "What SAMP version am I running?"
AI should call `list-clients` → `get-game-info` and respond with version.
## 🧪 Verification that it works
### Check 1: Landing Site
Open in browser: **http://127.0.0.1:16385/**
What should be:
- Hero with animated particles (electric blue color)
- **Install** section with 4 cards
- **Tools** section with 40 tools
- **AI Clients** section with 11 cards and "Copy config" button
- **Live Status** section — updates every 3 seconds
- **Saved Scripts** section — updates every 5 seconds
### Check 2: Health Endpoint
```bash
curl http://127.0.0.1:16385/health
# Should return: {"ok":true,"clients":0}
```
### Check 3: Connector in Moonloader
After launching GTA SA + SAMP, open the landing page. In the **Live Status** section, it should appear:
```
Bridge ● Listening on :16385
Connected Clients 1
Client c-xxxxxxx ● YourNick @ ServerName (1.2.3.4:7777)
```
If the client does not appear, open the Moonloader console (`~` in-game) and check for errors.
### Check 4: AI Client
In your AI client, ask:
> "List my connected SAMP clients"
The AI should call the MCP tool `list-clients` and return your data.
### Check 5: Script Saving and Injection
Ask the AI:
> "Save a Lua script named 'test.lua' with content `print('hello from samp-mcp')` and inject it"
After this:
- On the landing page, in the **Saved Scripts** section, `test.lua` should appear
- In the Moonloader console (open `~` in-game), the line `hello from samp-mcp` should appear
- The AI can read the output through `watch-script-output(basename='test.lua')`
## 🛠 Tool List
The AI can call these tools. Full documentation for each is in the Tools section on the landing page.
### 👥 Clients (2)
- `list-clients` — list of connected SAMP clients
- `set-active-client` — select active client (prefix-match)
### ⚡ Lua Execution (2)
- `execute-lua` — execute Lua without return value (fire-and-forget)
- `eval-return` — execute Lua and return value (bounded serialization)
### 🌐 Server and Game (4)
- `get-server-info` — hostname, IP:port, players, mode, ping
- `get-game-info` — SAMP/Moonloader/GTA versions, pool addresses
- `get-local-player` — position, HP, armor, money, weapon, vehicle
- `get-player-list` — nearby SAMP players with distances
### 🧠 Memory (4)
- `get-pool-summary` — pool counters (peds, vehicles, objects, pickups)
- `search-memory` — search by pool with filters (model, HP, position, skin)
- `read-struct` — read structure fields (CPed, CVehicle, CObject, ...)
- `write-struct` — write structure fields (with optional verify)
### 📡 RPC Spy (3)
- `rpc-spy-control` — start/stop/clear/status of spy
- `get-rpc-spy-logs` — logs of intercepted RPC packets
- `send-rpc` — send arbitrary RPC (by id or name)
### 🖱 GUI and Input (3)
- `send-dialog-response` — respond to open dialog
- `send-chat` — send message or /command
- `press-key` — simulate key press (VK or SAMP control)
### 📂 Moonloader Scripts (3)
- `list-scripts` — list of .lua files in moonloader/
- `get-script` — source of specific script (with pagination)
- `script-grep` — server-side regex search across all .lua scripts
### 💾 AI Workspace (5) — NEW
- `save-lua-script` — save Lua to `scripts/` (persistent storage)
- `inject-lua-script` — loadstring script into Moonloader immediately
- `list-saved-scripts` — list of saved scripts
- `get-saved-script` — source of saved script
- `delete-saved-script` — delete saved script
### 🌍 World Understanding (5) — NEW
- `get-nearby-entities` — all entities within radius with positions/velocities/heading
- `raycast` — check line of sight (obstacle or not)
- `get-vehicle-details` — full info about vehicle: speed, heading, quaternion, occupants
- `get-camera-state` — camera position and direction
- `get-screen-state` — what's on screen: dialog, cursor, scoreboard, visible players
### 📡 Server Context (2) — NEW
- `get-event-history` — last 500 events (chat, joins, deaths, dialogs)
- `discover-server` — auto-check: /cmdlist + /rules + RPC spy for 5 seconds
### 🛠 Workflow Development (6) — NEW
- `watch-script-output` — intercept print() of specific script
- `reload-script` — reload script (cooperative through flag)
- `list-templates` — list of available templates
- `get-template` — source of template
- `get-samp-function-reference` — search across ~50 SAMP functions
- `get-resource-doc` — read sampev-events.md / memory-layout.md
### 📸 Vision (1)
- `screenshot-window` — JPEG screenshot of gta_sa.exe window
## 💡 Usage Examples
### Example 1: Simple HP Monitoring
**Ask the AI:**
> "Save a Lua script that prints my HP, armor, and money every second, then inject it."
**What happens:**
1. AI calls `save-lua-script(path="hp_monitor.lua", source="...")`
2. AI calls `inject-lua-script(path="hp_monitor.lua")`
3. Connector saves file in `moonloader/hp_monitor.lua` and loadstring's it
4. AI calls `watch-script-output(basename="hp_monitor.lua")` and shows output
### Example 2: Auto-Respond to Dialog
**Ask the AI:**
> "Watch for SAMP dialogs and tell me when one appears. Then auto-respond with button 1."
**What happens:**
1. AI calls `get-event-history(filter="Dialog")` — sees dialog history
2. AI calls `get-screen-state` — sees current dialog (id, caption, body)
3. AI calls `send-dialog-response(button=1, listItem=0, inputText="")`
4. If necessary, AI saves resident script via `save-lua-script` + `inject-lua-script`
### Example 3: Auto-Drive
**Ask the AI:**
> "Use the auto-drive template to make my car drive forward, braking when there's an obstacle."
**What happens:**
1. AI calls `list-templates` — finds `auto-drive`
2. AI calls `get-template(file="auto-drive.lua")` — reads source
3. AI calls `get-samp-function-reference(query="raycast")` — checks API
4. AI calls `get-resource-doc(doc="memory-layout.md")` — checks CVehicle offsets
5. AI modifies template, calls `save-lua-script` + `inject-lua-script`
6. In-game, press **F1** to enable auto-drive
### Example 4: Exploring a New Server
**Ask the AI:**
> "I just connected to a new server. Discover what commands it has and what RPCs it sends."
**What happens:**
1. AI calls `get-server-info` — basic info
2. AI calls `discover-server` — runs /cmdlist, /help, /rules with RPC spy
3. AI calls `rpc-spy-control(action="start")` for continuous monitoring
4. AI calls `get-event-history(filter="Chat")` — sees recent messages
5. AI summarizes: what commands are available, what RPCs the server uses
## 🌐 Landing Site
After launching MCP server, open **http://127.0.0.1:16385/** in browser.
**What's there:**
- **Hero** — animated particle canvas (Atlantic.vc-style)
- **Install** — 4 cards with copy-paste code for installation
- **Tools** — all 40 MCP tools in grid with descriptions
- **AI Clients** — 11 cards, each with "Copy config" button and link to docs
- **Live Status** — polls `/api/clients` every 3 seconds, shows connected clients
- **Saved Scripts** — polls `/api/scripts/list` every 5 seconds, Inject/Delete buttons
**Design:** Atlantic.vc-inspired — dark charcoal canvas, ice-white wireframes, electric cobalt (#1f58f2) accents, signal orange (#ff4105) for CTA. No shadows, flat surfaces, monospaced micro-labels.
## 🔌 HTTP API (for external scripts)
All endpoints available at `http://127.0.0.1:16385`. Can be used from any language for automation.
### Basic
| Method | Path | Purpose |
|-------|------|-----------|
| GET | `/` | Landing page (HTML) |
| GET | `/assets/*` | CSS, JS, fonts |
| GET | `/script.lua` | Connector source (for `loadstring(downloadFile(...))()`) |
| GET | `/health` | Liveness probe: `{"ok":true,"clients":N}` |
### API for AI Workspace
| Method | Path | Purpose |
|-------|------|-----------|
| GET | `/api/clients` | List of connected SAMP clients (JSON) |
| GET | `/api/install-info` | Config snippets for 11 AI clients |
| GET | `/api/scripts/list` | List of saved scripts |
| GET | `/api/scripts/get?path=foo.lua` | Source of specific script |
| POST | `/api/scripts/save?action=save` | Save script (body: `{path, source, overwrite}`) |
| POST | `/api/scripts/inject?action=inject` | Save + inject (body: `{path?, source?, clientId?}`) |
| DELETE | `/api/scripts/delete?path=foo.lua` | Delete script |
### Example: Save and Inject Script via curl
```bash
# Save
curl -X POST "http://127.0.0.1:16385/api/scripts/save?action=save" \
-H "Content-Type: application/json" \
-d '{"path":"hello.lua","source":"print(\"hi from curl\")","overwrite":true}'
# Inject
curl -X POST "http://127.0.0.1:16385/api/scripts/inject?action=inject" \
-H "Content-Type: application/json" \
-d '{"path":"hello.lua"}'
# Check list
curl http://127.0.0.1:16385/api/scripts/list
```
## 🔧 Troubleshooting
### Problem: MCP Server Doesn't Start
**Symptom:** `node dist/index.js` throws an error or crashes.
**Solutions:**
1. Check Node.js version: `node --version` (must be ≥ 18)
2. Ensure you've run `npm install` and `npm run build`
3. Verify that the `dist/` folder exists and contains `index.js`
4. Check the full error output in stderr
### Problem: Connector Doesn't Connect
**Symptom:** The landing page shows "None connected" in Live Status.
**Solutions:**
1. Ensure the MCP server is running (`node dist/index.js`)
2. Verify that `connector.lua` and `ws-client.lua` are in `moonloader/`
3. Open the Moonloader console in-game (press `~`) and check for errors
4. Check if port 16385 is not occupied by another application:
```bash
netstat -ano | findstr :16385
```
5. Verify that Moonloader loaded the script — `moonloader.log` should contain `[samp-mcp] connector starting`
### Problem: AI Client Doesn't See MCP Tools
**Symptom:** No tools from samp-mcp are available in Claude Code / Cursor.
**Solutions:**
1. Check if the config is correct (path to `dist/index.js` must be absolute)
2. In Claude Code, run `/mcp` — it should show samp-mcp with a green checkmark
3. Restart the AI client after changing the config
4. Verify that the path in `args` uses double backslashes: `C:\\path\\to\\dist\\index.js`
5. In Windows PowerShell, ensure the path is enclosed in quotes if there are spaces
### Problem: AI Can't Invoke Tool
**Symptom:** AI calls `list-clients` and receives an error "No active SAMP client".
**Solutions:**
1. Check if GTA SA + SAMP are running
2. Verify that the connector has loaded (Live Status section on the landing page)
3. If there are multiple SAMP windows — use `set-active-client(prefix="...")`
### Problem: Memory Access Returns 0 or Crashes Game
**Symptom:** `read-struct` returns zeros, `write-struct` crashes GTA.
**Solutions:**
1. First, call `get-game-info` — verify that SAMP version is indeed 0.3.7 R3
2. First, call `get-pool-summary` — if all pools are 0, it means pools haven't initialized yet (wait for spawn)
3. **ALWAYS** call `read-struct` before `write-struct` to check the address
4. If using a non-standard SAMP build (Arizona, SRV, etc.) — offsets might differ
### Problem: Inject Doesn't Work
**Symptom:** `inject-lua-script` returns an error.
**Solutions:**
1. Ensure the connector is connected (Live Status shows the client)
2. Check for syntax errors in Lua code — connector will return `loadstring error: ...`
3. File name must match `^[A-Za-z0-9_-]+\.lua$` — no paths, no subdirectories
### Problem: Screenshot Doesn't Work
**Symptom:** `screenshot-window` returns an error.
**Solutions:**
1. Screenshots work **only on Windows** (uses PowerShell + user32)
2. Ensure GTA SA is running and the window is titled "GTA:SA:MP" or "GTA: San Andreas"
3. Run AI client as administrator (sometimes required for BitBlt)
### Problem: Performance
**Symptom:** Game lags with active RPC spy.
**Solutions:**
1. Use `rpc-spy-control(action="start", logPayloads=false)` — don't decode payloads
2. Regularly call `rpc-spy-control(action="clear")` to avoid log accumulation
3. Don't call `get-nearby-entities` with radius > 200 — will scan many pools
4. Use `summaryOnly=true` where full data isn't needed
---
## ⚠️ Security and Anti-Cheat
This fork supports **memory reading and writing** and **sending arbitrary RPCs**. On servers with anti-cheat, this may lead to a ban.
### ✅ Recommended Scenarios
- Local development of Moonloader scripts
- Connecting to your test server
- Reverse-engineering RPC in a controlled environment
- Studying SAMP 0.3.7 R3 memory structure
### ❌ Not Recommended Scenarios
- Public servers with anti-cheat (Phoenix, Arizona RP, SRV, Arizona, etc.)
- Servers that explicitly prohibit automation
- Any illegal activity
### Security Rules
1. **ALWAYS** call `read-struct` before `write-struct` — check the address
2. Don't send RPC packets without understanding their format (use `rpc-spy-control` first)
3. Don't modify memory on servers with anti-cheat-mod (except reading)
4. Don't use `send-rpc` to fake synchronization (services like RakNet detect this)
---
## 🔄 Differences from Original roblox-executor-mcp
| Aspect | Original (Roblox) | This Fork (SAMP) |
|--------|-------------------|------------------|
| Game | Roblox | GTA:SA + SAMP 0.3.7 R3 |
| Environment | Roblox executor (Luau) | Moonloader (Lua 5.1) |
| Decompiler needed? | Yes (Luau bytecode) | No — `.lua` source code is plaintext |
| RPC spy | Cobalt library | `sampev.onReceiveRpc/onSendRpc` (built-in) |
| Entity tree | `search-instances` (CSS selectors) | `search-memory` (predicate search by pools) |
| **AI workspace** | — | **NEW**: save/inject/list/get/delete-saved-script |
| **Auto-injector** | — | **NEW**: connector saves + loadstring's AI scripts |
| **Landing site** | — | **NEW**: http://127.0.0.1:16385/ with live status |
| **AI client configs** | — | **NEW**: 11 ready-made snippets |
| **Templates** | — | **NEW**: 6 ready-made Lua templates |
| **Resource docs** | — | **NEW**: sampev-events.md, memory-layout.md, samp-functions.json |
| **Event history** | — | **NEW**: auto-capture chat/dialogs/joins/deaths |
| **Script output watch** | — | **NEW**: intercept print() by source |
| Multi-client | Yes | Yes |
| Transport | WS + HTTP polling | WebSocket only |
| Primary/Secondary | Yes (cross-OS) | No (one host) |
| Screenshot | Roblox window | `gta_sa.exe` (same PowerShell approach) |
| Port | 16384 | **16385** (to avoid conflicts if both installed) |
---
## 📄 License and Credits
**License:** MIT — like the original.
**Credits:**
- **Original project:** [notpoiu/roblox-executor-mcp](https://github.com/notpoiu/roblox-executor-mcp) — architecture, MCP patterns, factory helpers, output budgeting
- **SAMP.Lua / Moonloader** — without them, this fork wouldn't be possible
- **SAMP 0.3.7 R3 memory layout** — documented by SA-MP modding community
- **Design system:** Atlantic.vc — midnight observatory palette (charcoal canvas, ice-white wireframes, electric cobalt accents, signal orange CTAs)
---
## 🎯 What's Next
After installation and verification:
1. **Explore the landing page** at http://127.0.0.1:16385/ — all 40 tools are listed with descriptions
2. **Try a simple script**: ask AI to save and inject `print("hello")`
3. **Use a template**: ask AI to take `hp-monitor.lua` as a basis for your script
4. **Study RPC**: run `rpc-spy-control` and perform an action in-game — see what the server sends
5. **Experiment with auto-drive**: load a template, get into a car, press F1
Good luck! 🚀
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available