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.

Related MCP server: Minecraft Ops MCP

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:

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

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.