> English | Español
Control the Arma 3 Eden Editor with natural language using any MCP-compatible AI (Claude Code, etc.).
Controla el Eden Editor de Arma 3 en lenguaje natural usando cualquier IA compatible con MCP.
English
What is this?
An MCP (Model Context Protocol) server that bridges an AI assistant (such as Claude Code in VS Code) to the Arma 3 Eden Editor. You can create entities, move objects, read terrain data, search locations, look up the BI Wiki, and more — all by chatting with your AI.
Architecture```
VS Code (Claude Code / any MCP client)
│ stdio / JSON-RPC 2.0
▼
Python MCP Server (mcp_server/)
│ Named Pipe \.\pipe\arma3_mcp_bridge
▼
C++ Bridge DLL (arma3_mcp_bridge_x64.dll)
│ callExtension / RVExtensionRegisterCallback
▼
Arma 3 Eden Editor (@ArmaDevBridge addon / SQF)
The MCP server runs outside Arma 3. The DLL acts as a bridge over a Windows named pipe. The SQF addon runs inside Eden Editor, executes commands, and shows a status indicator in the top bar.
### Prerequisites
| Tool | Min. version | Notes |
|---|---|---|
| Windows 10/11 (64-bit) | — | **Administrator rights required** — see note below |
| Arma 3 | 2.02 | Steam or standalone |
| Python | 3.9+ | python.org |
| pywin32 | any | `pip install pywin32` |
| Visual Studio Code | any | with any MCP-compatible AI — how to add an AI to VS Code |
> **Why Administrator?** Arma 3 runs as Administrator by default, which means the named pipe it creates requires elevated access. VS Code (and therefore the MCP server) must also run as Administrator, otherwise the pipe connection will be refused.
### Quick Install (5 steps)```bat
REM 1. Clone the repository
git clone https://github.com/YOUR_USER/arma3-eden-mcp "MCP Arma 3"
cd "MCP Arma 3"
REM 2. Install Python dependencies
pip install -r mcp_server/requirements.txt
pip install pywin32
REM 3. Pack and deploy the PBO addon (close Arma 3 first)
python tools/pack_pbo.py arma3_addon/addons/bridge bridge.pbo
copy bridge.pbo "K:\SteamLibrary\steamapps\common\Arma 3\@ArmaDevBridge\addons\bridge.pbo"
REM 4. Copy the DLL to the Arma 3 root folder
copy arma3_addon\addons\bridge\arma3_mcp_bridge.dll "K:\SteamLibrary\steamapps\common\Arma 3\arma3_mcp_bridge_x64.dll"
REM 5. Configure .mcp.json
copy .mcp.json.example .mcp.json
REM Then edit .mcp.json and replace PATH_TO_PYTHON and PATH_TO_PROJECT
Detailed Installation Guide
Step 1 — Clone and install Python dependencies```bat
git clone https://github.com/YOUR_USER/arma3-eden-mcp "MCP Arma 3"
cd "MCP Arma 3"
pip install -r mcp_server/requirements.txt
pip install pywin32
`pywin32` is required for named-pipe I/O on Windows and is not listed in `requirements.txt` because it is platform-specific.
#### Step 2 — Pack and deploy the PBO
The PBO (Packed BO) is the compiled Arma 3 addon. Build it from the SQF sources with:```bash
# Close Arma 3 before running this — the file is locked while the game is open
python tools/pack_pbo.py arma3_addon/addons/bridge bridge.pbo
cp bridge.pbo "K:/SteamLibrary/steamapps/common/Arma 3/@ArmaDevBridge/addons/bridge.pbo"
Create the mod folder if it does not exist:```bat
mkdir "K:\SteamLibrary\steamapps\common\Arma 3\@ArmaDevBridge\addons"
#### Step 3 — Copy the DLL```bat
copy arma3_addon\addons\bridge\arma3_mcp_bridge.dll "K:\SteamLibrary\steamapps\common\Arma 3\arma3_mcp_bridge_x64.dll"
> The DLL must be placed in the root of Arma 3 (next to arma3_x64.exe), not inside @ArmaDevBridge/addons/.
Step 4 — Configure `.mcp.json````bat
copy .mcp.json.example .mcp.json
Edit `.mcp.json` and replace the placeholder values:```json
{
"mcpServers": {
"arma3-eden": {
"type": "stdio",
"command": "C:\\Users\\YOUR_USER\\AppData\\Local\\Programs\\Python\\Python313\\python.exe",
"args": ["-m", "mcp_server"],
"cwd": "C:\\Users\\YOUR_USER\\Desktop\\MCP Arma 3",
"env": {
"ARMA3_BRIDGE_PIPE": "\\\\.\\pipe\\arma3_mcp_bridge",
"ARMA3_BRIDGE_TIMEOUT": "30"
}
}
}
}
To find your Python path: open a terminal and run where python or py -c "import sys; print(sys.executable)".
Step 5 — Launch Arma 3 and VS Code as Administrator
- Right-click Arma 3 in Steam → Properties → Launch Options → add
-mod=@ArmaDevBridge
Or launch from the command line:"K:\SteamLibrary\steamapps\common\Arma 3\arma3_x64.exe" -mod=@ArmaDevBridge - Open the Eden Editor. A status indicator appears in the top bar:
| Color | Status |
|---|---|
| Yellow | Initializing |
| Green | Bridge active, DLL connected |
| Red | DLL not found |
| White (flash) | Command received |
- Right-click VS Code → "Run as Administrator"
- Open the project folder in VS Code. Claude Code detects the MCP server from
.mcp.jsonautomatically. - Verify the connection: ask Claude "Is the bridge connected?" — it should respond with status
ok: true.
Available MCP Tools
Entities
| Tool | Description |
|---|---|
create_entity |
Create an entity (vehicle, unit, object, trigger…). Automatic ground-snapping (z=0 ATL = ground level). Vehicles created as Object have no crew. |
delete_entity |
Delete an entity by ID |
move_entity |
Move an entity to a new position |
list_all_entities |
List all entities of a given type in the mission |
get_all_editor_objects |
All objects with full details (paginated) |
get_all_editor_objects_full |
Same but unpaginated (small missions) |
get_selected_entities |
Entities currently selected in the editor |
Attributes
| Tool | Description |
|---|---|
set_attribute |
Set a 3DEN attribute (skill, fuel, health, ammo, init, isPlayable…) |
get_attribute |
Read a specific attribute of an entity |
get_all_attributes |
Read all Eden attributes including inventory/cargo |
Class Search
| Tool | Description |
|---|---|
find_classname |
Find the exact classname of a vehicle/unit by display name |
get_placeable_categories |
List available categories/factions for placement |
search_placeable_objects |
Search placeable classes by name or faction |
Mission
| Tool | Description |
|---|---|
get_mission_info |
Mission metadata (terrain, author, entity counts) |
save_mission |
Save the mission (with optional name) |
clear_mission |
Delete all entities (undoable with Ctrl+Z) |
undo_last_action |
Undo the last action |
get_bridge_status |
Check connection to Arma 3 |
Terrain and Map
| Tool | Description |
|---|---|
get_terrain_info |
Terrain height (ASL), water status, and surface type for one or more positions |
get_roads |
Road segments near a position (type, width, bridge flag) |
get_map_objects |
Terrain objects nearby: buildings, trees, walls, rocks, roads… |
find_location |
Search named map locations (cities, villages, hills, airports…) |
Wiki
| Tool | Description |
|---|---|
wiki_lookup |
Look up an Arma 3 SQF command or function from the local BI Wiki mirror |
wiki_search |
Full-text search across 5,000+ BI Wiki articles |
Memory / Context for AI
The .claude/memory/ directory contains structured context files that Claude Code (and other AI assistants) load automatically when working on this project:
| File | Contents |
|---|---|
MEMORY.md |
Index of all memory files |
project_arma3_mcp.md |
Architecture, key files, PBO workflow, gotchas |
feedback_eden_spawning.md |
Mandatory spawning rules: ground snap, water surface, clearance radius, crew removal, waypoint water/land rules |
user_profile.md |
User technical background and preferences |
If you clone this repo and open it with Claude Code, these files will be picked up automatically — no extra configuration needed.
Building from Source
Repack the PBO (after modifying SQF files)```bash
Close Arma 3 first
python tools/pack_pbo.py arma3_addon/addons/bridge /tmp/bridge.pbo
cp /tmp/bridge.pbo "K:/SteamLibrary/steamapps/common/Arma 3/@ArmaDevBridge/addons/bridge.pbo"
#### Rebuild the DLL (only if you modify the C++ code)
From WSL with MinGW-w64 installed:```bash
cd tools
bash build_dll_wsl.sh
Or on Windows with MSVC:```bat
cd bridge_dll
cmake -B build -A x64
cmake --build build --config Release
The compiled DLL must then be copied to the Arma 3 root as `arma3_mcp_bridge_x64.dll`.
#### Adding a new SQF function
Every new SQF function **must** be registered in **two places** in `fn_init.sqf`:
1. `uiNamespace setVariable ["ArmaDevBridge_fnc_X", compile preprocessFileLineNumbers ...]`
2. `ArmaDevBridge_bridge_fnc_X = uiNamespace getVariable "ArmaDevBridge_fnc_X"`
Missing either step results in the function being `nil` at runtime → silent timeout.
### Troubleshooting
**Status indicator does not appear in Eden Editor**
Verify that `bridge.pbo` is in `@ArmaDevBridge\addons\` and the mod is active. Check `%LOCALAPPDATA%\Arma 3\arma3_x64_*.rpt` for `ArmaDevBridge` errors.
**DLL not found (red indicator)**
The DLL must be `arma3_mcp_bridge_x64.dll` in the **root** of Arma 3 (next to `arma3_x64.exe`), not inside the addon folder.
**Claude Code does not show MCP tools**
- Verify `.mcp.json` points to the correct Python executable: `python.exe --version` should return 3.9+.
- Reload VS Code (`Ctrl+Shift+P` → "Developer: Reload Window").
- Confirm `mcp` is installed: `python -m mcp_server` should not show import errors.
- Make sure VS Code is running as Administrator.
**"Bridge not connected" error**
Arma 3 must be open with the Eden Editor active (not in preview mode, not in a mission). Check the pipe exists:```powershell
[System.IO.Directory]::GetFiles("\\.\pipe\") | Select-String "arma3"
Timeout on tool calls
The pipe connects but SQF is not responding. Verify EachFrame was registered in the log. If you added a new SQF function, ensure it appears in both sections of fn_init.sqf.
Entities spawning underground or floating
Redeploy the PBO — an older version of fn_createEntity.sqf may be active.
Known Limitations
- Undo:
undo_last_actionis a placeholder; useCtrl+Zmanually in the editor. - Preview mode: when entering preview the addon unloads; the bridge reconnects when returning to the editor.
- One client at a time: the DLL accepts only one Python connection simultaneously.
- BattlEye: designed exclusively for local editor use. Not compatible with multiplayer protected by BE.
- Unnamed missions:
save_missionon a new unnamed mission does not create a.sqmfile until the user assigns a name from the editor.
License
MIT
Español
¿Qué es esto?
Un servidor MCP (Model Context Protocol) que conecta un asistente de IA (como Claude Code en VS Code) con el Eden Editor de Arma 3. Puedes crear entidades, mover objetos, leer datos del terreno, buscar ubicaciones, consultar la Wiki de BI, y más — todo conversando con tu IA.
Arquitectura```
VS Code (Claude Code / cualquier cliente MCP)
│ stdio / JSON-RPC 2.0
▼
Servidor Python MCP (mcp_server/)
│ Named Pipe \.\pipe\arma3_mcp_bridge
▼
DLL Bridge C++ (arma3_mcp_bridge_x64.dll)
│ callExtension / RVExtensionRegisterCallback
▼
Arma 3 Eden Editor (addon @ArmaDevBridge / SQF)
El servidor MCP corre fuera de Arma 3. La DLL actúa como puente usando un named pipe de Windows. El addon SQF corre dentro del Eden Editor, ejecuta los comandos y muestra un indicador de estado en la barra superior.
### Requisitos previos
| Herramienta | Versión mínima | Notas |
|---|---|---|
| Windows 10/11 (64-bit) | — | **Permisos de Administrador obligatorios** — ver nota |
| Arma 3 | 2.02 | Steam o standalone |
| Python | 3.9+ | python.org |
| pywin32 | cualquiera | `pip install pywin32` |
| Visual Studio Code | cualquiera | con cualquier IA compatible con MCP — cómo añadir una IA a VS Code |
> **¿Por qué Administrador?** Arma 3 se ejecuta como Administrador por defecto, lo que significa que el named pipe que crea requiere acceso elevado. VS Code (y por tanto el servidor MCP) también debe ejecutarse como Administrador, de lo contrario la conexión al pipe será rechazada.
### Instalación rápida (5 pasos)```bat
REM 1. Clonar el repositorio
git clone https://github.com/YOUR_USER/arma3-eden-mcp "MCP Arma 3"
cd "MCP Arma 3"
REM 2. Instalar dependencias Python
pip install -r mcp_server/requirements.txt
pip install pywin32
REM 3. Empaquetar y desplegar el PBO (cerrar Arma 3 primero)
python tools/pack_pbo.py arma3_addon/addons/bridge bridge.pbo
copy bridge.pbo "K:\SteamLibrary\steamapps\common\Arma 3\@ArmaDevBridge\addons\bridge.pbo"
REM 4. Copiar la DLL a la raíz de Arma 3
copy arma3_addon\addons\bridge\arma3_mcp_bridge.dll "K:\SteamLibrary\steamapps\common\Arma 3\arma3_mcp_bridge_x64.dll"
REM 5. Configurar .mcp.json
copy .mcp.json.example .mcp.json
REM Editar .mcp.json y reemplazar PATH_TO_PYTHON y PATH_TO_PROJECT
Guía de instalación detallada
Paso 1 — Clonar e instalar dependencias Python```bat
git clone https://github.com/YOUR_USER/arma3-eden-mcp "MCP Arma 3"
cd "MCP Arma 3"
pip install -r mcp_server/requirements.txt
pip install pywin32
`pywin32` es necesario para la E/S del named pipe en Windows y no está en `requirements.txt` porque es específico de plataforma.
#### Paso 2 — Empaquetar y desplegar el PBO
El PBO es el addon compilado de Arma 3. Se genera a partir de las fuentes SQF con:```bash
# Cerrar Arma 3 antes — el archivo queda bloqueado mientras el juego está abierto
python tools/pack_pbo.py arma3_addon/addons/bridge bridge.pbo
cp bridge.pbo "K:/SteamLibrary/steamapps/common/Arma 3/@ArmaDevBridge/addons/bridge.pbo"
Crear la carpeta del mod si no existe:```bat
mkdir "K:\SteamLibrary\steamapps\common\Arma 3\@ArmaDevBridge\addons"
#### Paso 3 — Copiar la DLL```bat
copy arma3_addon\addons\bridge\arma3_mcp_bridge.dll "K:\SteamLibrary\steamapps\common\Arma 3\arma3_mcp_bridge_x64.dll"
> La DLL debe estar en la raíz de Arma 3 (junto a arma3_x64.exe), no dentro de @ArmaDevBridge/addons/.
Paso 4 — Configurar `.mcp.json````bat
copy .mcp.json.example .mcp.json
Edita `.mcp.json` y reemplaza los valores de ejemplo:```json
{
"mcpServers": {
"arma3-eden": {
"type": "stdio",
"command": "C:\\Users\\TU_USUARIO\\AppData\\Local\\Programs\\Python\\Python313\\python.exe",
"args": ["-m", "mcp_server"],
"cwd": "C:\\Users\\TU_USUARIO\\Desktop\\MCP Arma 3",
"env": {
"ARMA3_BRIDGE_PIPE": "\\\\.\\pipe\\arma3_mcp_bridge",
"ARMA3_BRIDGE_TIMEOUT": "30"
}
}
}
}
Para encontrar tu ruta de Python: abre una terminal y ejecuta where python o py -c "import sys; print(sys.executable)".
Paso 5 — Lanzar Arma 3 y VS Code como Administrador
- Clic derecho en Arma 3 en Steam → Propiedades → Opciones de lanzamiento → añade
-mod=@ArmaDevBridge
O desde línea de comandos:"K:\SteamLibrary\steamapps\common\Arma 3\arma3_x64.exe" -mod=@ArmaDevBridge - Abre el Eden Editor. Aparece un indicador de estado en la barra superior:
| Color | Estado |
|---|---|
| Amarillo | Inicializando |
| Verde | Bridge activo, DLL conectada |
| Rojo | DLL no encontrada |
| Blanco (flash) | Recibiendo comando |
- Clic derecho en VS Code → "Ejecutar como administrador"
- Abre la carpeta del proyecto en VS Code. Claude Code detecta el servidor MCP desde
.mcp.jsonautomáticamente. - Verifica la conexión: pregúntale a Claude "¿Está el bridge conectado?" — debe responder con
ok: true.
Herramientas MCP disponibles
Entidades
| Herramienta | Descripción |
|---|---|
create_entity |
Crea una entidad (vehículo, unidad, objeto, trigger…). Ground-snapping automático (z=0 ATL = nivel del suelo). Los vehículos creados como Object no tienen tripulación. |
delete_entity |
Elimina una entidad por su ID |
move_entity |
Mueve una entidad a una nueva posición |
list_all_entities |
Lista todas las entidades de un tipo en la misión |
get_all_editor_objects |
Todos los objetos con detalles completos (paginado) |
get_all_editor_objects_full |
Igual pero sin paginación (misiones pequeñas) |
get_selected_entities |
Entidades seleccionadas actualmente en el editor |
Atributos
| Herramienta | Descripción |
|---|---|
set_attribute |
Modifica un atributo 3DEN (skill, fuel, health, ammo, init, isPlayable…) |
get_attribute |
Lee un atributo concreto de una entidad |
get_all_attributes |
Lee todos los atributos Eden, incluyendo inventario/cargo |
Búsqueda de clases
| Herramienta | Descripción |
|---|---|
find_classname |
Encuentra el classname exacto de un vehículo/unidad por nombre |
get_placeable_categories |
Lista las categorías/facciones disponibles para colocar |
search_placeable_objects |
Busca clases de objetos colocables por nombre o facción |
Misión
| Herramienta | Descripción |
|---|---|
get_mission_info |
Información de la misión (terreno, autor, conteos de entidades) |
save_mission |
Guarda la misión (con nombre opcional) |
clear_mission |
Borra todas las entidades del editor (deshacible con Ctrl+Z) |
undo_last_action |
Deshace la última acción |
get_bridge_status |
Verifica la conexión con Arma 3 |
Terreno y mapa
| Herramienta | Descripción |
|---|---|
get_terrain_info |
Altura del terreno (ASL), si es agua y tipo de superficie para una o varias posiciones |
get_roads |
Segmentos de carretera cercanos a una posición (tipo, ancho, si es puente) |
get_map_objects |
Objetos del terreno cercanos: edificios, árboles, muros, rocas, carreteras… |
find_location |
Busca ubicaciones con nombre en el mapa (ciudades, pueblos, colinas, aeropuertos…) |
Wiki
| Herramienta | Descripción |
|---|---|
wiki_lookup |
Consulta un comando o función SQF de Arma 3 desde la copia local de la Wiki de BI |
wiki_search |
Búsqueda de texto completo en más de 5.000 artículos de la Wiki de BI |
Memoria / Contexto para IA
El directorio .claude/memory/ contiene archivos de contexto estructurado que Claude Code (y otros asistentes de IA) cargan automáticamente al trabajar en este proyecto:
| Archivo | Contenido |
|---|---|
MEMORY.md |
Índice de todos los archivos de memoria |
project_arma3_mcp.md |
Arquitectura, archivos clave, flujo del PBO, gotchas |
feedback_eden_spawning.md |
Reglas obligatorias de spawn: ground snap, superficie del agua, radio de clearance, eliminación de tripulación, reglas de waypoints tierra/agua |
user_profile.md |
Perfil técnico del usuario y preferencias |
Si clonas este repositorio y lo abres con Claude Code, estos archivos se cargarán automáticamente — no se necesita ninguna configuración adicional.
Compilar desde el código fuente
Reempaquetar el PBO (tras modificar archivos SQF)```bash
Cerrar Arma 3 primero
python tools/pack_pbo.py arma3_addon/addons/bridge /tmp/bridge.pbo
cp /tmp/bridge.pbo "K:/SteamLibrary/steamapps/common/Arma 3/@ArmaDevBridge/addons/bridge.pbo"
#### Recompilar la DLL (solo si modificas el código C++)
Desde WSL con MinGW-w64 instalado:```bash
cd tools
bash build_dll_wsl.sh
O en Windows con MSVC:```bat
cd bridge_dll
cmake -B build -A x64
cmake --build build --config Release
La DLL compilada debe copiarse a la raíz de Arma 3 como `arma3_mcp_bridge_x64.dll`.
#### Añadir una nueva función SQF al bridge
Toda función SQF nueva **debe** registrarse en **dos sitios** de `fn_init.sqf`:
1. `uiNamespace setVariable ["ArmaDevBridge_fnc_X", compile preprocessFileLineNumbers ...]`
2. `ArmaDevBridge_bridge_fnc_X = uiNamespace getVariable "ArmaDevBridge_fnc_X"`
Si falta cualquiera de los dos, la función es `nil` en runtime → timeout silencioso.
### Solución de problemas
**El indicador no aparece en el Eden Editor**
Verifica que `bridge.pbo` está en `@ArmaDevBridge\addons\` y que el mod está activo. Revisa `%LOCALAPPDATA%\Arma 3\arma3_x64_*.rpt` buscando errores de `ArmaDevBridge`.
**DLL no encontrada (indicador rojo)**
La DLL debe ser `arma3_mcp_bridge_x64.dll` en la **raíz** de Arma 3 (junto a `arma3_x64.exe`), no dentro de la carpeta del addon.
**Claude Code no muestra las herramientas MCP**
- Verifica que `.mcp.json` apunta al Python correcto: `python.exe --version` debe dar 3.9+.
- Recarga VS Code (`Ctrl+Shift+P` → "Developer: Reload Window").
- Confirma que `mcp` está instalado: `python -m mcp_server` no debe dar errores de importación.
- Asegúrate de que VS Code se ejecuta como Administrador.
**Error "Bridge not connected"**
Arma 3 debe estar abierto con el Eden Editor activo (no en modo preview, no en misión). Verifica el pipe en PowerShell:```powershell
[System.IO.Directory]::GetFiles("\\.\pipe\") | Select-String "arma3"
Timeout en las herramientas
El pipe conecta pero SQF no responde. Verifica que EachFrame se registró en el log. Si añadiste una función SQF nueva, asegúrate de que aparece en ambas secciones de fn_init.sqf.
Entidades aparecen bajo tierra o flotando
Redespliega el PBO — puede estar activa una versión antigua de fn_createEntity.sqf.
Limitaciones conocidas
- Undo:
undo_last_actiones un placeholder; usaCtrl+Zmanualmente en el editor. - Modo preview: al entrar en preview el addon se descarga; el bridge se reconecta al volver al editor.
- Un cliente a la vez: la DLL acepta una sola conexión Python simultánea.
- BattlEye: diseñado exclusivamente para uso local en el editor. No compatible con multijugador protegido por BE.
- Misiones sin nombre:
save_missionen una misión nueva sin nombre no crea un archivo.sqmen disco hasta que el usuario le dé nombre desde el editor.
Licencia
MIT
