io.github.headlesshq/headlessmc-mcp

What it mainly works on, as our AI model read its tool descriptions: files and code on the machine it runs on.

14 of 21 tools are described as changing something (creating, editing, deleting, sending or running).

• chaton 28 other serverssends messagesdescribed as changing data

  “Sends a chat message, or a command if it starts with a slash, e.g.”

  2 inputs, 2 required

  • instancestringrequired“The instance id.”
  • messagestringrequired“The message or /command.”
• clickon 27 other serverscontrols a browser or desktopdescribed as changing data

  “Clicks a button of the current screen, by the id from get_screen.”

  3 inputs, 2 required

  • instancestringrequired“The instance id.”
  • elementIdintegerrequired“The id of the element from get_screen.”
  • buttoninteger“Mouse button, 0 is left, 1 is right.”
• connecton 1,144 other serversdescribed as changing data

  “Connects the client to a server.”

  3 inputs, 2 required

  • instancestringrequired“The instance id.”
  • hoststringrequired“Host name or ip of the server.”
  • portinteger“Port of the server.”
• create_profileon 10 other serversdescribed as changing data

  “Creates a profile with its own game directory and installs its version.”

  4 inputs, 2 required

  • namestringrequired“Name of the profile: letters, digits, '.', '_' and '-'.”
  • versionstringrequired“Minecraft version, e.g.”
  • loaderstring“Modloader: fabric, forge, neoforge or vanilla.”
  • timeoutSecondsinteger“How long to wait for installing the version.”
• delete_profileon 7 other serversdeletesdescribed as changing data

  “Deletes a profile.”

  Publisher declares: read-only no · destructive yes · idempotent no · open-world yes

  2 inputs, 1 required

  • namestringrequired“Name of the profile.”
  • deleteFilesboolean“Also delete the game directory of the profile.”
• disconnecton 13 other serversdescribed as changing data

  “Disconnects the client from the server or leaves the singleplayer world.”

  1 input, 1 required

  • instancestringrequired“The instance id.”
• game_commandruns code or commandsdescribed as changing data

  “Executes any HMC-Specifics command inside the client and returns its output, e.g.”

  3 inputs, 2 required

  • instancestringrequired“The instance id.”
  • commandstringrequired“The command line.”
  • timeoutSecondsinteger“How long the game may take to execute the command.”
• get_screenon 6 other serversreads or searches

  “Returns the screen the client currently displays as JSON: its class name and all buttons and text fields with their ids, texts, positions and whether they are enabled.”

  Publisher declares: read-only yes · destructive yes · idempotent no · open-world yes

  1 input, 1 required

  • instancestringrequired“The instance id.”
• get_stateon 13 other serversreads or searches

  “Returns the state of the client as JSON: whether it is in a world, dead, the current screen, and metrics like position, health, food, dimension, server address, ping, TPS and the player list.”

  Publisher declares: read-only yes · destructive yes · idempotent no · open-world yes

  1 input, 1 required

  • instancestringrequired“The instance id.”
• hmcruns code or commandsdescribed as changing data

  “Runs a HeadlessMc command line and returns its output, like the `headlessmc` CLI, without the leading `headlessmc`.”

  2 inputs, 1 required

  • commandstringrequired“The command line, e.g.”
  • timeoutSecondsinteger“How long to wait for the command.”
• hmc_jobreads or searches

  “Returns the output and status of a HeadlessMc command started by the hmc tool.”

  Publisher declares: read-only yes · destructive yes · idempotent no · open-world yes

  1 input, 1 required

  • jobIdstringrequired“The job id returned by the hmc tool.”
• instance_logreads or searches

  “Returns the latest lines of an instance's output (the game or server log).”

  Publisher declares: read-only yes · destructive yes · idempotent no · open-world yes

  3 inputs, 1 required

  • instancestringrequired“The instance id.”
  • linesinteger“How many lines to return.”
  • filterstring“Only return lines matching this regular expression.”

Each quoted sentence is the first sentence of the publisher’s own description. The kind of tool and the “changes data” mark are our AI model’s reading of that description, not something we tested: two differently worded runs had to agree, otherwise no label is shown, and nobody has checked them by hand. A tool without the “changes data” mark is described as only reading, searching or calculating, or the two runs did not agree. No tool was called. Read the publisher’s full description before relying on it. “Publisher declares” lists the hints the server itself sends with the tool (MCP annotations: read-only, destructive, idempotent, open-world); they are the publisher's claims, not checked by us. Inputs are the parameters in the tool's own input schema: name, declared type, whether it is required, and the first sentence of its description. Read 2026-10-23.

The registry verifies a package once, when it is published, and does not re-check it. A difference below is about the listing, not a judgement of the publisher.