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:

Variable	Purpose
BEAMNG_MOD_ROOT	Required writable mod workspace
BEAMNG_GAME_ROOT	Optional read-only BeamNG installation/content root
BEAMNG_DOCS_CACHE	Optional documentation cache location
BEAMNG_DOCS_TTL_HOURS	Cache freshness interval; defaults to 24

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

Tool	Purpose
beamng_docs_search	Search the synchronized official documentation
beamng_docs_get	Read a cached page/section or fetch one approved URL
beamng_docs_sync	Refresh the bounded documentation cache
beamng_source_search	Search optional local game text files read-only
beamng_mod_scaffold	Generate one of seven text-only mod templates
beamng_mod_write_files	Atomically write bounded UTF-8 changes
beamng_mod_validate	Check structure, JBeam, JSON, materials, references, and metadata
beamng_mod_package	Validate and create a deterministic ZIP
beamng_best_practices	Return evidence-backed rules by mod type/topic

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.