DCS Lua Runner MCP Server

An MCP (Model Context Protocol) server that enables AI assistants to interact with DCS World (Digital Combat Simulator) in real-time through chat.

Features

This MCP server provides the following tools for AI interaction with DCS:

Tools Available

1. execute_lua - Execute arbitrary Lua code on DCS server

   • Execute custom Lua scripts
   • Choice of mission or GUI environment
   • Returns execution results

2. get_mission_info - Get current mission information

   • Mission time
   • Theatre/map name
   • Mission date

3. get_player_info - Get player aircraft information

   • Aircraft name and type
   • Position (x, y, z coordinates)
   • Altitude
   • Speed
   • Heading

4. get_all_units - List all units in the mission

   • Filter by coalition (red, blue, neutral, or all)
   • Unit names, types, positions
   • Coalition affiliations

5. spawn_unit - Spawn new units in the mission

   • Ground units or vehicles
   • Specify position, heading, coalition
   • Custom unit names

6. send_message - Display messages in DCS

   • Send text messages to all players
   • Configurable display duration

7. get_theatre_info - Get theatre/map information

   • Current map name
   • Theatre details

8. get_aircraft_list - List all aircraft in mission

   • All airborne units
   • Positions and altitudes
   • Coalition information

9. convert_coordinates - Convert real-world coordinates to DCS

   • Convert Lat/Long (decimal degrees) to DCS X/Z coordinates
   • Optional altitude parameter
   • Uses the theatre's native coord.LLtoLO DCS API

10. convert_dcs_to_ll - Convert DCS coordinates to Lat/Long

    • Convert DCS X/Z to real-world Latitude/Longitude
    • Optional Y/altitude parameter
    • Uses the theatre's native coord.LOtoLL DCS API

Prerequisites

1. DCS World installed with DCS Fiddle server running
2. Node.js installed (for running the MCP server)

Configuration

The MCP server reads settings from dcs_lua_runner_settings.json in the following priority order:

1. Environment Variable (if set): Path specified in DCS_SETTINGS_PATH
2. MCP Server Directory (default): dcs_lua_runner_settings.json in the same folder as the MCP server
3. Fallback Defaults: If no settings file is found, uses default localhost configuration

Quick Setup

1. Copy the template file:

   cp dcs_lua_runner_settings.json.template dcs_lua_runner_settings.json
   

2. Edit the settings file with your DCS server details (the defaults work for most local setups)

The MCP server will automatically find and load the settings file from its own directory.

Settings Used

• server_address - DCS server address for remote connections
• server_port - Port for mission environment (default: 12080)
• server_address_gui - GUI environment server address
• server_port_gui - Port for GUI environment (default: 12081)
• use_https - Whether to use HTTPS
• web_auth_username - Username for authentication
• web_auth_password - Password for authentication
• run_code_locally - Execute on local server (127.0.0.1)
• run_in_mission_env - Execute in mission vs GUI environment

Installation

Method 1: Direct Installation (Pre-built)

The release zip already contains the pre-built build/index.js — no Node.js build step required.

1. Extract the release zip (e.g. dcs-lua-runner-mcp-v1.1.0.zip) to your preferred location, e.g.:

   C:\dcs-lua-runner-mcp\
   

2. Run the installer script — open PowerShell, navigate to the extracted folder and run:

   .\install-mcp-agent.ps1
   

   The script walks you through two steps automatically:

   Step 1 — DCS Server Settings

   • Asks whether DCS runs on the same machine (local) or on a remote IP
   • Prompts for port, username, and password (current/template values shown in brackets — press Enter to keep)
   • Saves the result to dcs_lua_runner_settings.json
   • Also patches dcs-fiddle-server.lua with IP, port, username and password — no need to edit it separately

   Step 2 — Agent Registration

   • Shows a numbered menu of supported agents with their config status
   • Enter one or more numbers separated by commas or spaces, or type all
   • Type skip (or press Enter with no input) to skip agent registration entirely
   • Patches each selected agent config file (creates the file if it doesn't exist yet)

   1. Claude Desktop
   2. Cline (VS Code extension)
   3. GitHub Copilot Chat (VS Code)
   4. Cursor
   5. Windsurf
   6. Claude Code CLI
   7. GitHub Copilot CLI
   

   Tip: You can skip the interactive prompts entirely with flags:

   # Configure specific agents (e.g. Copilot Chat + Cline)
   .\install-mcp-agent.ps1 -AgentIds 2,3
   
   # Configure all agents at once
   .\install-mcp-agent.ps1 -All
   
   # Skip agent registration (only update settings + fiddle script)
   .\install-mcp-agent.ps1 -SkipAgents
   
   # Point to a build in a custom location
   .\install-mcp-agent.ps1 -ServerPath "D:\tools\dcs-mcp\build\index.js"
   

3. Install the DCS server script — copy dcs-fiddle-server.lua into your DCS mission scripts or into the DCS Scripts\Hooks folder and load it (see DCS Server Script Installation).

4. Restart your agent (reload VS Code, restart Claude Desktop, etc.) to apply the configuration changes.

Method 2: Installation from GitHub

1. Clone the repository:

   git clone https://github.com/sevenfifty777/dcs-lua-runner-mcp.git
   cd dcs-lua-runner-mcp
   

2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

4. Configure settings and register agents:

   Option A — Automatic (recommended): Run the installer script, which handles everything in one go:

   .\install-mcp-agent.ps1
   

   The script will:

   • Prompt for DCS server settings and save dcs_lua_runner_settings.json
   • Patch dcs-fiddle-server.lua with the same values automatically
   • Let you pick which agents to register from a numbered menu (type skip to skip this step)

   Option B — Manual:

   Copy the template and fill in your DCS server details:

   cp dcs_lua_runner_settings.json.template dcs_lua_runner_settings.json
   

   Edit dcs_lua_runner_settings.json:

   {
     "server_address": "127.0.0.1",
     "server_port": 12080,
     "server_address_gui": "127.0.0.1",
     "server_port_gui": 12081,
     "use_https": false,
     "web_auth_username": "your_username",
     "web_auth_password": "your_password",
     "run_code_locally": true,
     "run_in_mission_env": true,
     "return_display_format": "lua"
   }
   

   Then update your agent's MCP config file to point to build/index.js. Place dcs_lua_runner_settings.json in the same directory as the MCP server so it is found automatically.

   For Cline (VS Code) — edit %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json:

   {
     "mcpServers": {
       "dcs-lua-runner-mcp": {
         "command": "node",
         "args": ["C:/absolute/path/to/dcs-lua-runner-mcp/build/index.js"]
       }
     }
   }
   

   For Claude Desktop — edit %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

   {
     "mcpServers": {
       "dcs-lua-runner-mcp": {
         "command": "node",
         "args": ["C:/absolute/path/to/dcs-lua-runner-mcp/build/index.js"]
       }
     }
   }
   

   For GitHub Copilot Chat (VS Code) — edit %APPDATA%\Code\User\mcp.json:

   {
     "servers": {
       "dcs-lua-runner-mcp": {
         "command": "node",
         "args": ["C:/absolute/path/to/dcs-lua-runner-mcp/build/index.js"],
         "type": "stdio"
       }
     }
   }
   

   For GitHub Copilot CLI — edit %USERPROFILE%\.copilot\mcp-config.json:

   {
     "mcpServers": {
       "dcs-lua-runner-mcp": {
         "command": "node",
         "args": ["C:/absolute/path/to/dcs-lua-runner-mcp/build/index.js"],
         "type": "stdio"
       }
     }
   }
   

   Custom settings path — if dcs_lua_runner_settings.json lives elsewhere, pass its path via environment variable:

   {
     "mcpServers": {
       "dcs-lua-runner-mcp": {
         "command": "node",
         "args": ["C:/absolute/path/to/dcs-lua-runner-mcp/build/index.js"],
         "env": {
           "DCS_SETTINGS_PATH": "C:/custom/path/to/dcs_lua_runner_settings.json"
         }
       }
     }
   }
   

5. Install the DCS server script — copy dcs-fiddle-server.lua into your DCS mission scripts or into the DCS Scripts folder and load it (see DCS Server Script Installation).

6. Restart your agent (reload VS Code, restart Claude Desktop, etc.)

7. Test the connection:

   Ask your AI assistant: "What's the current mission time in DCS?"

Verification

After installation, verify the MCP server is working:

1. Check that build/index.js exists
2. Ensure DCS World is running with DCS Fiddle server
3. Ask your AI assistant to get mission info
4. Check MCP server logs in your client for any errors

Usage Examples

Once the MCP server is running, you can ask your AI assistant to interact with DCS:

Get Mission Information

"What's the current mission time in DCS?"
"What theatre/map am I flying in?"

Get Player Information

"Where is my aircraft?"
"What's my current altitude and speed?"

Spawn Units

"Spawn a T-72B tank at coordinates x=100000, z=200000 for the red coalition"
"Create an M-1 Abrams at position 150000, 250000 facing north"

Send Messages

"Send a message to all players saying 'Mission starting in 5 minutes'"

Execute Custom Lua

"Execute this Lua code in DCS: return timer.getTime()"
"Run this script to get all blue coalition units"

List Units and Aircraft

"Show me all units in the mission"
"List all red coalition aircraft"
"What aircraft are currently in the mission?"

Convert Coordinates

"Convert latitude 41.123, longitude 44.987 to DCS coordinates"
"What are the DCS X/Z coordinates for lat 51.5, lon 37.2?"
"Convert DCS coordinates X=100000, Z=200000 to latitude/longitude"
"What is the real-world position of the unit at DCS X=50000, Z=150000?"

DCS Setup Requirements

⚠️ Security Notice: Setting up DCS Fiddle requires disabling DCS sandboxing and, optionally, exposing a network port. Read DCS_Setup_Risks.md for a full risk assessment and mandatory security measures before proceeding.

1. DCS Fiddle Server Installation

Step 1 — Locate your Saved Games folder

DCS uses a folder under Windows Saved Games to store user scripts. The exact name depends on your DCS branch:

DCS Branch	Saved Games Folder
DCS World (stable)	%USERPROFILE%\Saved Games\DCS
DCS World OpenBeta	%USERPROFILE%\Saved Games\DCS.openbeta

Open File Explorer and navigate to the correct path, e.g.:

C:\Users\<YourUser>\Saved Games\DCS

Step 2 — Create the Hooks folder (if it does not exist)

Inside your Saved Games DCS folder, create the following folder structure if it is not already there:

Saved Games\DCS\Scripts\Hooks\

On Windows you can do this from PowerShell:

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\Saved Games\DCS\Scripts\Hooks"

For OpenBeta replace DCS with DCS.openbeta.

Step 3 — Copy the server script

Copy dcs-fiddle-server.lua from this repository into the Hooks folder:

Copy-Item ".\dcs-fiddle-server.lua" "$env:USERPROFILE\Saved Games\DCS\Scripts\Hooks\"

The final path should look like:

%USERPROFILE%\Saved Games\DCS\Scripts\Hooks\dcs-fiddle-server.lua

Step 4 — Verify the script is loaded

After launching DCS, open %USERPROFILE%\Saved Games\DCS\Logs\dcs.log and search for:

DCS Fiddle successfully initialized

If you see this line the server is running and listening on ports 12080 (mission environment) and 12081 (GUI environment).

Note: The Hooks folder is loaded by DCS at startup for both the main menu (GUI environment) and in-mission. You do not need to add anything to autoexec.cfg.

2. DCS Desanitization

⚠️ Security Warning: This step disables DCS sandboxing and grants scripts full system access. See DCS_Setup_Risks.md for the full risk details and how to restore security afterwards.

Edit DCS_INSTALL\Scripts\MissionScripting.lua and comment out these two lines:

--  _G['require'] = nil      -- comment this out
    _G['loadlib'] = nil
--  _G['package'] = nil      -- comment this out

3. Start DCS

1. Launch DCS World
2. The DCS Fiddle server will start automatically
3. Verify the server is running (check DCS.log for "DCS Fiddle successfully initialized")

Troubleshooting

Connection Errors

Error: "Connection refused - check if DCS Fiddle server is running"

• Solution: Ensure DCS is running and DCS Fiddle server is installed correctly

Error: "Request timeout - check server connection"

• Solution: Check if DCS Fiddle server is bound to the correct address/port
• Verify firewall settings if using remote connections

Authentication Errors

Error: Unauthorized (401)

• Solution: Check username/password in dcs_lua_runner_settings.json
• Ensure authentication settings match DCS Fiddle server configuration

Execution Errors

Error: "No player found"

• Solution: Ensure you're in a mission with a player-controlled aircraft
• Try switching between mission and GUI environments

Error: Lua execution errors

• Solution: Check Lua syntax and DCS API availability
• Some functions only work in mission environment

Testing with MCP Inspector

The MCP Inspector is a developer tool that allows you to test and debug your MCP server interactively before integrating it with an AI client.

Running the Inspector

1. Ensure the project is built:

   npm run build
   

2. Start the MCP Inspector:

   npm run inspector
   

3. Using the Inspector:

   • The inspector will open in your default web browser
   • You'll see an interactive GUI showing:
     • Available Tools: List of all 10 DCS interaction tools
     • Tool Parameters: Input fields for each tool's parameters
     • Request/Response: Real-time display of MCP communication
     • Test Results: Output from each tool execution

4. Testing Individual Tools:

   • Select a tool from the list (e.g., get_mission_info)
   • Fill in required parameters (if any)
   • Click "Execute" to test the tool
   • View the response in JSON format

5. Example Test Scenarios:

   • Test connection: Use get_mission_info to verify DCS connection
   • Test Lua execution: Use execute_lua with simple code like return "Hello from DCS"
   • Test spawning: Use spawn_unit with test coordinates
   • Debug errors: View detailed error messages and stack traces

Inspector Benefits

• No AI client needed: Test without configuring Cline or Claude Desktop
• Interactive debugging: See requests and responses in real-time
• Parameter validation: Verify tool inputs before integration
• Quick iteration: Test changes immediately after rebuilding

Notes

• The inspector runs the MCP server in a test environment
• You still need DCS World running with the Fiddle server for actual DCS interaction
• The inspector uses the same dcs_lua_runner_settings.json configuration

Development

Building from Source

cd C:\{your_path}\dcs-lua-runner-mcp
npm install
npm run build

Project Structure

dcs-lua-runner-mcp/
├── src/
│   └── index.ts          # Main MCP server implementation
├── build/
│   └── index.js          # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

Adding New Tools

To add new DCS interaction tools:

1. Add tool definition to ListToolsRequestSchema handler
2. Implement tool logic in CallToolRequestSchema handler
3. Rebuild: npm run build

Security Considerations

• Local Execution: By default, executes on 127.0.0.1 (localhost only)
• Remote Execution: Requires authentication (username/password)
• Code Validation: All Lua code is base64-encoded before transmission
• DCS Security: Requires DCS desanitization (understand the risks!)

License

MIT License - Based on the DCS Lua Runner GUI project

Credits

• Original DCS Fiddle: JonathanTurnock and john681611
• DCS Lua Runner VSCode Extension: omltcat
• GUI Implementation: Created for standalone Windows application
• Model Context Protocol: MCP SDK by Anthropic

Support

For issues related to:

• MCP Server: Check the build output and MCP settings
• DCS Connection: Verify DCS Fiddle server installation
• Lua Execution: Check DCS.log for detailed error messages

LobeHub