BeamNG Modding MCP

A local Model Context Protocol server for researching, scaffolding, reviewing, validating, and packaging BeamNG.drive mods. Official BeamNG documentation results include their source URL and freshness metadata; optional game-source searches are read-only.

Requirements and setup

• Node.js 20 or newer

• A directory dedicated to your mod projects

cd /Users/joaorodrigues/Documents/beamng-mcp
npm install
npm run build

Choose a workspace. Every server write is confined to this directory:

mkdir -p /absolute/path/to/beamng-mod-workspace

Optional environment variables:

Related MCP server: enfusion-mcp

Connect an MCP client

Replace /absolute/path/to/beamng-mod-workspace in these examples.

Codex

The installed Codex CLI can create the stdio registration directly:

codex mcp add beamng-modding \
  --env BEAMNG_MOD_ROOT=/absolute/path/to/beamng-mod-workspace \
  -- node /Users/joaorodrigues/Documents/beamng-mcp/dist/index.js

Add optional environment variables by repeating --env. Confirm the registration with:

codex mcp get beamng-modding

Start a new Codex task after adding the server so its tools are discovered.

Claude Desktop

Add this server under mcpServers in Claude Desktop's MCP configuration:

{
  "mcpServers": {
    "beamng-modding": {
      "command": "node",
      "args": ["/Users/joaorodrigues/Documents/beamng-mcp/dist/index.js"],
      "env": {
        "BEAMNG_MOD_ROOT": "/absolute/path/to/beamng-mod-workspace"
      }
    }
  }
}

Restart Claude Desktop after saving the configuration.

Cursor

Create .cursor/mcp.json in the project that should use the server:

{
  "mcpServers": {
    "beamng-modding": {
      "command": "node",
      "args": ["/Users/joaorodrigues/Documents/beamng-mcp/dist/index.js"],
      "env": {
        "BEAMNG_MOD_ROOT": "/absolute/path/to/beamng-mod-workspace"
      }
    }
  }
}

VS Code

Create .vscode/mcp.json:

{
  "servers": {
    "beamng-modding": {
      "type": "stdio",
      "command": "node",
      "args": ["/Users/joaorodrigues/Documents/beamng-mcp/dist/index.js"],
      "env": {
        "BEAMNG_MOD_ROOT": "/absolute/path/to/beamng-mod-workspace"
      }
    }
  }
}

Run MCP: List Servers from the Command Palette to start or inspect it.

First use

Populate the local official-documentation index. Either ask the client:

Synchronize the BeamNG modding documentation with beamng_docs_sync, then find the official guidance for creating a vehicle configuration.

Or run the CLI task with the same environment:

BEAMNG_MOD_ROOT=/absolute/path/to/beamng-mod-workspace npm run docs:sync

The server keeps cached pages available when offline. Refreshes are same-origin and restricted to https://documentation.beamng.com/modding/.

Example requests:

• “Plan a BeamNG Lua extension, citing the official docs.”

• “Dry-run a vehicle mod scaffold named rally_buggy in rally-buggy.”

• “Validate the mod in rally-buggy and explain every error with sources.”

• “Search my configured BeamNG source for onExtensionLoaded examples.”

• “Package rally-buggy as releases/rally-buggy.zip after it passes validation.”

Scaffolding and general file writes default to dryRun: true. Ask explicitly to apply the operation after reviewing the planned paths.

Tools

The server also publishes documentation, templates, best practices, and the latest validation report as MCP resources, plus four reusable workflow prompts.

Development

npm run check

The tests cover path traversal and symlink containment, atomic overwrite behavior, documentation extraction/search, tolerant JBeam parsing, all scaffold profiles, deterministic archive layout, and MCP discovery/tool execution.

Safety and limitations

• The server never installs mods or changes BeamNG game files.

• All authoring paths are relative to BEAMNG_MOD_ROOT; symlink escapes and traversal are rejected.

• Static validation cannot prove physics, rendering, Lua runtime behavior, or gameplay correctness. Test the packaged ZIP in BeamNG.drive.

• Documentation is incomplete in some areas. Official docs, configured local game source, and curated guidance are always labeled separately.