io.github.truetick-gg/mcp

TrueTick MCP Server

Manage TrueTick Minecraft servers directly from an AI agent. This MCP server exposes 30 tools covering the server-facing part of the TrueTick public API — lifecycle, console, metrics and tick history, files, backups, mods, templates and wallet — to Claude and other compatible AI clients.

It is not the whole API: the public surface is 98 operations. Networks, capacity and regions have no tools here at all, and of the account-scoped operations only the wallet is covered (get_wallet) — the ledger, account limits and checkout links are not. For those, call the REST API directly.

Installation & Setup

1. Get an API Key

Visit truetick.gg/dashboard/api-keys to create an API key. Select the scopes you need (e.g., servers:read, servers:write, billing:read).

2. Configure Claude Desktop

Add the following to your Claude Desktop config file (%APPDATA%\Claude\claude_desktop_config.json on Windows, ~/Library/Application Support/Claude/claude_desktop_config.json on Mac, or ~/.config/Claude/claude_desktop_config.json on Linux):

{
  "mcpServers": {
    "truetick": {
      "command": "npx",
      "args": ["-y", "@truetick/mcp"],
      "env": {
        "TRUETICK_API_KEY": "ttk_your_key_here"
      }
    }
  }
}

Replace ttk_your_key_here with your actual API key.

3. Configuration

The MCP server reads its configuration from environment variables:

• TRUETICK_API_KEY (required): Your TrueTick API key with appropriate scopes.
• TRUETICK_API_URL (optional, defaults to https://api.truetick.gg): The API endpoint. Override for testing against a different environment.

Tool Catalog

Account & Wallet

• whoami — Show the account your API key is bound to.
• list_servers — List all your Minecraft servers.
• get_wallet — Show your wallet balance and recent transactions.

Server Management

• create_server — Create a new Minecraft server (specify name, RAM, server type, version, region, billing plan).
• get_server — Get details of a specific server.
• start_server — Start a stopped server.
• stop_server — Stop a running server.
• restart_server — Restart a running server.
• delete_server — Permanently delete a server and all its data.
• update_server_version — Change the server type and/or version (server must be stopped).
• set_server_properties — Update server.properties keys and optional idle timeout.
• set_server_motd — Set the server's Message of the Day (MOTD).
• list_templates — List the server templates (presets) you can create from.
• create_server_from_template — Create a server from a template preset.

Console & Metrics

• run_command — Run a console (RCON) command on a running server.
• get_server_metrics — Get live TPS/MSPT/player count metrics for a server. Read tps together with tpsSource: TPS_SOURCE_UNSPECIFIED means there is no reading, not zero performance.
• get_server_tick_history — One-minute buckets of tick health (default 24h, max 720). Minutes the server slept through have no row at all — a gap is a real gap, never a zero.
• get_recent_logs — Fetch the most recent container log lines for a server (snapshot).

File Management

• list_files — List files in a directory on the server.
• read_file — Read the contents of a file on the server.
• write_file — Write content to a file on the server.
• delete_file — Delete a file on the server.

Backups

• create_backup — Create an on-demand backup of the server.
• list_backups — List available backups for the server.
• restore_backup — Restore a backup (server must be stopped; overwrites current data).
• set_backup_kept — Keep a backup (kept: true) out of rotation until it is unkept, or put it back (kept: false). Up to 3 per server; kept backups count toward the server's backup space.

Mods & Plugins

• list_mods — List mods/plugins installed on the server.
• add_mod — Add a mod or plugin from Modrinth or CurseForge.
• list_mod_versions — List the builds of a mod or plugin that this server can pin (its loader and Minecraft version only, pre-releases included); pass one as version to add_mod.
• remove_mod — Remove a mod or plugin from the server.

Development

npm run build      # Compile TypeScript
npm test           # Run tests
npm start          # Run the MCP server (for manual testing)

License

MIT — see LICENSE.

About this repository

Development of TrueTick happens in a private monorepo; this repository mirrors released versions of @truetick/mcp. Issues and discussions are welcome right here — for code contributions, please propose the change in an issue first.

Related: TypeScript SDK & CLI · developer docs · truetick.gg/developers