ark-asa-mcp

ark-asa-mcp is a Node.js Model Context Protocol server for Ark: Survival Ascended servers that expose RCON.

It lets an MCP client run common ASA administration commands through a small, typed tool surface while keeping one or more RCON server definitions in a local config.json file.

Features

• MCP stdio server built with @modelcontextprotocol/sdk.
• RCON command execution against one or more named Ark: Survival Ascended servers.
• Per-tool serverName routing when multiple servers are configured.
• Convenience tools for listing players, broadcasting messages, saving the world, and reading the game log.
• Centralized configuration through config.json.
• Unit-tested command helpers for input validation and output shaping.

Requirements

• Node.js 20 or newer.
• One or more Ark: Survival Ascended servers with RCON enabled.
• The RCON host, port, and password for each configured server.

Install

Developer mode:

npm install
npm run build

User mode:

Download ark-asa-mcp-win-x64.zip from a GitHub release, extract it, copy config.example.json to config.json, and point your MCP client at ark-asa-mcp.exe.

Configuration

Copy config.example.json to config.json and edit the server definitions for your ASA hosts. The local config.json file is ignored by Git because it contains RCON passwords.

{
  "defaultServerName": "azer",
  "timeoutMs": 10000,
  "maxResponseChars": 20000,
  "servers": [
    {
      "serverName": "azer",
      "host": "127.0.0.1",
      "port": 27020,
      "password": "change-me"
    },
    {
      "serverName": "island",
      "host": "127.0.0.2",
      "port": 27020,
      "password": "change-me-too"
    }
  ]
}

By default, ark-asa-mcp reads config.json from the process working directory. You can point to another file with ARK_ASA_CONFIG_PATH:

ARK_ASA_CONFIG_PATH=D:/Repositories/ark-asa-mcp/config.json

Each server object supports:

Field	Required	Default	Notes
serverName	yes	none	Stable name used by MCP tools, such as azer.
host	no	127.0.0.1	ASA RCON host.
port	no	27020	ASA RCON port.
password	yes	none	ASA RCON password.
timeoutMs	no	top-level timeoutMs or 10000	Per-server timeout override.
maxResponseChars	no	top-level maxResponseChars or 20000	Per-server response cap.

defaultServerName is optional. If it is not set and only one server is configured, tools can omit serverName. If more than one server is configured, tools should pass serverName.

Environment fallback is still available for simple or containerized deployments:

ARK_ASA_RCON_SERVER_NAME=azer
ARK_ASA_RCON_HOST=127.0.0.1
ARK_ASA_RCON_PORT=27020
ARK_ASA_RCON_PASSWORD=change-me

ARK_ASA_RCON_SERVERS and ARK_RCON_* aliases are still accepted as fallbacks when no config file exists.

MCP Client Example

Release .exe mode:

{
  "mcpServers": {
    "ark-asa": {
      "command": "C:/Tools/ark-asa-mcp/ark-asa-mcp.exe"
    }
  }
}

If the config file lives elsewhere:

{
  "mcpServers": {
    "ark-asa": {
      "command": "C:/Tools/ark-asa-mcp/ark-asa-mcp.exe",
      "env": {
        "ARK_ASA_CONFIG_PATH": "C:/Tools/ark-asa-mcp/config.json"
      }
    }
  }
}

Node mode:

{
  "mcpServers": {
    "ark-asa": {
      "command": "node",
      "args": ["D:/Repositories/ark-asa-mcp/dist/index.js"],
      "env": {
        "ARK_ASA_CONFIG_PATH": "D:/Repositories/ark-asa-mcp/config.json"
      }
    }
  }
}

For development, you can point the command at tsx:

{
  "mcpServers": {
    "ark-asa-dev": {
      "command": "npx",
      "args": ["tsx", "D:/Repositories/ark-asa-mcp/src/index.ts"],
      "env": {
        "ARK_ASA_CONFIG_PATH": "D:/Repositories/ark-asa-mcp/config.json"
      }
    }
  }
}

Tools

Tool	Purpose
asa_list_servers	Lists configured ASA RCON servers without exposing passwords.
asa_config_list_servers	Lists servers from config.json without exposing passwords.
asa_config_upsert_server	Creates or updates a server entry in config.json.
asa_config_remove_server	Removes a server entry from config.json.
asa_config_set_default_server	Sets the default server in config.json.
asa_rcon_command	Runs a raw RCON command.
asa_list_players	Runs ListPlayers and returns raw plus parsed player entries.
asa_broadcast	Runs Broadcast <message>.
asa_save_world	Runs SaveWorld.
asa_get_game_log	Runs GetGameLog.

Server-bound tools accept an optional serverName argument. It becomes required when multiple servers are configured and no default server is set.

Config-writing tools never return passwords, but any password supplied through an MCP client is still visible to that client. For local setup, ark-asa-mcp configure is safer.

The MCP server can start before any server is configured so asa_config_upsert_server can create the first config.json. RCON tools will return a clear error until at least one server exists.

CLI Commands

ark-asa-mcp configure
ark-asa-mcp configure --server-name azer --host 127.0.0.1 --port 27020 --password change-me --default
ark-asa-mcp config:list
ark-asa-mcp --version

configure creates or updates config.json interactively.

Releases

The release workflow builds a Windows x64 zip containing:

• ark-asa-mcp.exe
• config.example.json
• README-USER.md
• LICENSE

Push a tag like v0.1.0 to create or update a draft GitHub release asset.

Development

npm run typecheck
npm test
npm run build

The package entry point is src/index.ts. Build output is written to dist/.

Windows executable packaging uses Node.js single executable applications:

npm run package:win

This script expects Node.js 26 or newer.

Security Notes

RCON has server administrator authority. Treat every RCON password like a production secret, avoid committing .env files, and only expose this MCP server to clients you trust.

The raw command tool intentionally supports arbitrary single-line RCON commands. Newline characters are rejected to prevent accidental command batching.