Troubleshooting

Troubleshooting

minecraft-mcp writes its log to stderr. Claude Desktop shows it in its MCP logs, Claude Code under /mcp, and a terminal right under the command. Start there.

The server doesn't start

• “Set WORLDAPI_URL to the WorldAPI base URL”: the variable is missing. Add it to the client's env block.
• “WORLDAPI_URL isn't a URL” or “must use http or https”: check the address. It looks like http://localhost:8110/api/v1.
• “Set MCP_HTTP_TOKEN to listen on …”: with --http, any --host beyond 127.0.0.1, ::1, or localhost needs MCP_HTTP_TOKEN.
• npx not found: install Node.js 22 or newer, then restart the client. Claude Desktop's bundle doesn't need it.

The agent has fewer tools than expected

1. Read the start line in the log: WorldAPI <version> at <url>; permissions: …. It lists what the token got.
2. “Couldn't read the token's permissions over the WebSocket”: minecraft-mcp couldn't reach <url>/ws, or WorldAPI refused the token. It then assumes what anonymous clients get. Check that your proxy forwards WebSockets and that the token is right.
3. “read-only” at the end of the start line: WORLDAPI_READ_ONLY is on, so every tool that changes something is hidden.
4. Otherwise the token lacks the permission. Tools names the permission each tool needs; Tokens and permissions says how to make a bigger token.

Many tools fail

“WorldAPI x.y.z is older than 3.3.0”: update WorldAPI on the server. minecraft-mcp follows WorldAPI 3.3's endpoints.

A tool returns an error

Errors carry WorldAPI's own code, such as player_offline: …, or http_<status> when WorldAPI sent none. Most player tools need the player online. An error about the token means it's wrong, expired, or lacks the permission.

A config change didn't stick

The server reads most configs only at start, so restart it or reload the plugin. If your server copies its configs from a repository or a Docker image on every start, change them there instead.

Java tools are missing

They need the code permission and WorldAPI's scripts turned on in its config. admin doesn't include code; only owner does.

Still stuck? Open an issue with the start line from the log. Leave the token out.