Configuration

Configuration

minecraft-mcp reads its settings from environment variables. Your client passes them in its env block; Claude Desktop fills them from the extension's settings.

Environment variables

Variable	Required	What it does
WORLDAPI_URL	Yes	WorldAPI's address including /api/v1, such as http://localhost:8110/api/v1. It must use http or https.
WORLDAPI_TOKEN	No	A WorldAPI token. Its permissions decide which tools the agent gets. Without one, the agent sees what WorldAPI lets visitors read.
WORLDAPI_PLAYER	No	Your player name. “I”, “me”, and “my” mean this player, and tools that take a player use it when the agent leaves one out.
WORLDAPI_READ_ONLY	No	1, true, or yes hides every tool that changes anything, whatever the token allows.
MCP_HTTP_TOKEN	With --http beyond loopback	The bearer token HTTP clients must send.

Command-line flags

Flag	Default	What it does
--http	off	Serve Streamable HTTP at /mcp instead of stdio.
--host	127.0.0.1	Address to listen on with --http. Anything but 127.0.0.1, ::1, or localhost needs MCP_HTTP_TOKEN.
--port	3333	Port to listen on with --http.
--version		Print the version.
--help		Print the usage.

What happens at start

1. minecraft-mcp asks WorldAPI's WebSocket which permissions the token has.
2. It registers only the tools those permissions allow, and only read tools in read-only mode.
3. It checks WorldAPI's version and warns when it's older than 3.0.0.
4. It tells the agent which jobs the token can't do, so the agent says so instead of hunting for a missing tool.

Everything it logs goes to stderr, with the token blanked out.

Next: Tokens and permissions.