mcp-exaroton

MCP server for natural-language interaction with the Exaroton API, exposing account, server, file, configuration and player list management to MCP hosts (Claude Desktop, VS Code, Cursor and compatible clients).

Features

• Account and credits lookup, plus shared credit pools
• Server listing and resolution by friendly name (dashboard alias) — no need to know the server id
• Server lifecycle control (start/stop/restart), command execution, RAM, MOTD and auto-stop timer extension
• File read/write, directory creation and structured configuration editing (e.g. server.properties)
• Player list management (whitelist, ops, banned players)
• Log retrieval and sharing via mclo.gs

Available Tools

Tool	Description
get_account	Account data (name, email, credits)
list_credit_pools	Lists shared credit pools
get_credit_pool	Pool details: members and servers
list_servers	Lists servers in the account
get_server_status	Status, MOTD and players of a server
control_server	Starts, stops or restarts a server (idempotent)
execute_command	Executes a command on the console
get_ram / set_ram	Reads/changes allocated RAM (2–16 GB)
get_motd / set_motd	Reads/changes the message of the day
extend_stop_time	Extends the auto-stop timer
list_directory	Lists files/directories at a path
read_file / write_file	Reads/writes a file's content
delete_file	Deletes a file or directory
create_directory	Creates a new directory
get_config_options / set_config_option	Reads/changes options in a structured configuration file
list_player_lists	Lists available player lists (whitelist, ops, etc.)
get_player_list_entries	Lists entries of a player list
add_player_list_entries / remove_player_list_entries	Adds/removes entries from a player list
get_logs	Retrieves the most recent server log
share_logs	Shares the log via mclo.gs

Requirements

• Node.js 18+
• Exaroton API token (Exaroton dashboard → Account → API Key)

Configuration

Variable	Required	Default	Description
EXAROTON_API_TOKEN	Yes	—	Exaroton API token
MCP_TRANSPORT	No	stdio	Transport mode: stdio (default, for npx/Claude Desktop/VS Code) or http (Streamable HTTP, for Docker/remote clients)
MCP_HTTP_PORT	No	3004	HTTP server port (only used when MCP_TRANSPORT=http)
MCP_HTTP_HOST	No	0.0.0.0	HTTP server bind address (only used when MCP_TRANSPORT=http)

Security: never commit your real token. EXAROTON_API_TOKEN should be provided via environment (env var, orchestrator secret, etc.).

Usage

Run directly from GitHub

npx github:ferronicardoso/mcp-exaroton

Claude Desktop configuration

%APPDATA%\\Claude\\claude_desktop_config.json:

{
  "mcpServers": {
    "exaroton": {
      "command": "npx",
      "args": ["github:ferronicardoso/mcp-exaroton"],
      "env": {
        "EXAROTON_API_TOKEN": "your-token-here"
      }
    }
  }
}

VS Code MCP configuration

.vscode/mcp.json:

{
  "servers": {
    "exaroton": {
      "command": "npx",
      "args": ["github:ferronicardoso/mcp-exaroton"],
      "env": {
        "EXAROTON_API_TOKEN": "your-token-here"
      }
    }
  }
}

Running with Docker (HTTP transport)

The published image runs in Streamable HTTP mode by default, for use as a remote MCP endpoint:

docker run -d --name mcp-exaroton \
  -p 3004:3004 \
  -e EXAROTON_API_TOKEN=your-token-here \
  ghcr.io/ferronicardoso/mcp-exaroton:latest

The MCP endpoint is available at http://localhost:3004/mcp.

Local Development

git clone https://github.com/ferronicardoso/mcp-exaroton
cd mcp-exaroton
npm install
npm run build

Start the compiled server:

EXAROTON_API_TOKEN=your-token-here npm start

Tests

npm test

Tests mock fetch for the REST client and use an in-memory transport from @modelcontextprotocol/sdk for the tool handlers — no real calls are made to the Exaroton API.

Build and Commit Workflow

This repository intentionally versions dist/, to support usage via npx github:user/repo.

The project uses a Husky pre-commit hook to:

1. compile TypeScript (npm run build)
2. add the generated artifacts (git add dist)

Manual fallback:

npm run build
git add dist

Security Notes

• Never commit your real token or .env files.
• Use EXAROTON_API_TOKEN via environment for continuous use.
• Real-time streaming (live console, TPS, memory usage via WebSocket) is not exposed in this version — tools operate on a request/response basis.