MCP server

@truetick/mcp exposes the TrueTick API as Model Context Protocol tools, so an LLM agent (Claude Desktop and other MCP clients) can manage Minecraft servers in natural language. It's the same per-account, scope-gated API surface — just shaped as callable tools.

Setup

1. Get a scoped key

Create a ttk_ key in Dashboard → API keys (opens in a new tab) with the scopes the agent needs (e.g. servers:read, servers:write, console). See Authentication.

2. Configure your MCP client

Add the server to your client config (Claude Desktop's claude_desktop_config.json shown):

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

TRUETICK_API_KEY is required; TRUETICK_API_URL is optional (defaults to https://api.truetick.gg). Restart the client to load the tools.

The MCP server inherits the key's scopes. A read-only key produces a read-only agent — tool calls that need a missing scope fail with a permission error. Scope the key to the least the agent needs.

Tool catalog

Account & wallet

Tool	Description
`whoami`	Show the account the key is bound to
`list_servers`	List your servers
`get_wallet`	Wallet balance

Server lifecycle

Tool	Args	Description
`create_server`	`name`, `ramMb`, `type?`, `version?`, `region?`, `plan?`	Create a server
`get_server`	`serverId`	Server details
`start_server`	`serverId`	Start (wake) a server
`stop_server`	`serverId`	Stop a server
`restart_server`	`serverId`	Restart a server
`delete_server`	`serverId`	Destructive — delete a server and its data
`update_server_version`	`serverId`, `type`, `version`	Change core/version (stopped only)
`set_server_properties`	`serverId`, `properties`, `idleTimeoutMinutes?`	Patch `server.properties` + idle timeout
`set_server_motd`	`serverId`, `motd`	Set the MOTD

Console & metrics

Tool	Args	Description
`run_command`	`serverId`, `command`	Run an RCON command
`get_server_metrics`	`serverId`	Live TPS / MSPT / player metrics
`get_recent_logs`	`server_id`, `tail?`	Recent container log lines (snapshot)

Files

Tool	Args	Description
`list_files`	`serverId`, `path`	List a directory
`read_file`	`serverId`, `path`	Read a file
`write_file`	`serverId`, `path`, `content`	Write a file (text)
`delete_file`	`serverId`, `path`	Destructive — delete a file

Backups

Tool	Args	Description
`create_backup`	`serverId`	Create an on-demand backup
`list_backups`	`serverId`	List backups
`restore_backup`	`serverId`, `backupId`	Destructive — restore (stopped only, overwrites data)

Mods & templates

Tool	Args	Description
`list_mods`	`serverId`	List installed mods
`add_mod`	`serverId`, `source`, `projectId`, `version?`	Add a mod from Modrinth/CurseForge
`remove_mod`	`serverId`, `source`, `projectId`	Remove a mod
`list_templates`	—	List server templates
`create_server_from_template`	`templateId`, `name`, `ramMb?`, `region?`, `version?`, `plan?`	Create from a template

Example prompts

Once configured, ask your agent things like:

List my Minecraft servers and their states.

Create a 4 GB Paper 1.21.1 server called "test", start it, then show me its TPS.

Add Sodium from Modrinth to my "smp" server.

Take a backup of "smp", then show me the last 50 log lines.

⚠️

Tools marked Destructive (delete_server, delete_file, restore_backup) permanently remove or overwrite data. Review what the agent intends before approving those calls.

Prefer to wire the API into your own agent loop instead of MCP? See Programmatic control for agents and the SDK.

CLI API Reference