Other clients

Other clients

Any client that speaks MCP can run minecraft-mcp. Most start it over stdio with npx, which needs Node.js 22 or newer. Clients on other machines connect over HTTP.

VS Code

1. Create .vscode/mcp.json in your project.

2. Put this in it. VS Code asks for the token on the first start and keeps it out of the file:

   {
     "inputs": [
       { "type": "promptString", "id": "worldapi-token", "description": "WorldAPI token", "password": true }
     ],
     "servers": {
       "minecraft": {
         "type": "stdio",
         "command": "npx",
         "args": ["-y", "@mairwunnx/minecraft-mcp"],
         "env": {
           "WORLDAPI_URL": "http://localhost:8110/api/v1",
           "WORLDAPI_TOKEN": "${input:worldapi-token}"
         }
       }
     }
   }

3. Start the server from the file's code lens, or from the MCP list in the Extensions view.

Any stdio client

Put this block under whatever key your client's config uses for servers:

{
  "mcpServers": {
    "minecraft": {
      "command": "npx",
      "args": ["-y", "@mairwunnx/minecraft-mcp"],
      "env": {
        "WORLDAPI_URL": "http://localhost:8110/api/v1",
        "WORLDAPI_TOKEN": "your-token",
        "WORLDAPI_READ_ONLY": "1"
      }
    }
  }
}

WORLDAPI_READ_ONLY hides every tool that changes anything. Drop it once you trust the setup.

Over HTTP

Run minecraft-mcp once and connect agents from other machines, or clients that only speak HTTP.

1. Pick a long random secret for MCP_HTTP_TOKEN.

2. Start the server:

   MCP_HTTP_TOKEN=a-long-random-secret \
   WORLDAPI_URL=http://localhost:8110/api/v1 \
   WORLDAPI_TOKEN=your-token \
     npx -y @mairwunnx/minecraft-mcp --http --host 0.0.0.0 --port 3333

3. Point clients at http://<host>:3333/mcp and have them send Authorization: Bearer <MCP_HTTP_TOKEN>.

4. Put HTTPS in front of it before it leaves your network.

Without MCP_HTTP_TOKEN, the server listens only on 127.0.0.1, ::1, or localhost, and refuses to start with any other --host.

Next: Configuration.