1. Home
  2. Minecraft MCP Server
  3. Minecraft MCP Server for Windsurf: Setup & Config

Data as of

Minecraft MCP Server for Windsurf: Setup & Config

Windsurf: Minecraft MCP Server lets an AI assistant control a Minecraft character through Mineflayer.

What you can do with Minecraft in Windsurf

A focused Mineflayer-backed MCP bridge for hands-on assistant interaction with a Minecraft world.

  • Place and dig blocks during an assisted building session.
  • Read and send in-game messages while interacting with the world.

Before you start: Minecraft in Windsurf

  • Git
  • Node.js 20.10.0 or later
  • A running compatible Minecraft game with a reachable world
  • An MCP-compatible client

The README opens a single-player world to LAN and configures the bot's host and port to match. Its current support notice names Minecraft 1.21.11, while the setup walkthrough mentions testing Java Edition 1.21.8. Restart the desktop client fully after configuration. No required environment variables are stated.

Minecraft Windsurf configuration

  1. Choose Windsurf configuration scope

    For Minecraft MCP Server, open macOS/Linux: ~/.codeium/windsurf/mcp_config.json Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json. Merge into mcpServers; remote endpoints use serverUrl.

  2. Add Minecraft MCP Server to Windsurf

    Use the minecraft-mcp-server entry below in mcpServers. Keep Minecraft MCP Server's documented stdio connection fields and your other Windsurf entries.

  3. Check Minecraft MCP Server in Windsurf

    Minecraft MCP Server: Refresh MCP in Windsurf settings and inspect Cascade’s tools.

Config file · macOS/Linux: ~/.codeium/windsurf/mcp_config.json

Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json

JSON
{
  "mcpServers": {
    "minecraft-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "github:yuniko-software/minecraft-mcp-server",
        "--host",
        "localhost",
        "--port",
        "25565",
        "--username",
        "ClaudeBot"
      ],
      "env": {}
    }
  }
}

Minecraft tools available to Windsurf

Minecraft's stored tool list documents 18 tools; compare it with Windsurf's connected tool list, because the stored list is not a live check.

get-position

After refreshing Minecraft in Windsurf settings, check Cascade's tool list for get-position.

move-to-position

After refreshing Minecraft in Windsurf settings, check Cascade's tool list for move-to-position.

look-at

After refreshing Minecraft in Windsurf settings, check Cascade's tool list for look-at.

jump

After refreshing Minecraft in Windsurf settings, check Cascade's tool list for jump.

move-in-direction

After refreshing Minecraft in Windsurf settings, check Cascade's tool list for move-in-direction.

fly-to

After refreshing Minecraft in Windsurf settings, check Cascade's tool list for fly-to.

Fly directly toward a target position.

list-inventory

After refreshing Minecraft in Windsurf settings, check Cascade's tool list for list-inventory.

Inspect items currently carried by the bot.

find-item

After refreshing Minecraft in Windsurf settings, check Cascade's tool list for find-item.

Locate a particular item in the bot's inventory.

equip-item

After refreshing Minecraft in Windsurf settings, check Cascade's tool list for equip-item.

Equip a selected inventory item.

place-block

After refreshing Minecraft in Windsurf settings, check Cascade's tool list for place-block.

dig-block

After refreshing Minecraft in Windsurf settings, check Cascade's tool list for dig-block.

get-block-info

After refreshing Minecraft in Windsurf settings, check Cascade's tool list for get-block-info.

find-blocks

After refreshing Minecraft in Windsurf settings, check Cascade's tool list for find-blocks.

smelt-item

After refreshing Minecraft in Windsurf settings, check Cascade's tool list for smelt-item.

Process items using a furnace-like block.

find-entity

After refreshing Minecraft in Windsurf settings, check Cascade's tool list for find-entity.

Locate the closest entity matching a requested type.

send-chat

After refreshing Minecraft in Windsurf settings, check Cascade's tool list for send-chat.

Post a message to the game's chat.

read-chat

After refreshing Minecraft in Windsurf settings, check Cascade's tool list for read-chat.

Read recent messages sent by players.

detect-gamemode

After refreshing Minecraft in Windsurf settings, check Cascade's tool list for detect-gamemode.

Determine the current game mode.

Minecraft: full stored tool descriptions

Troubleshooting Minecraft in Windsurf

  • Check npx (Node.js/npm) on the machine running Windsurf's MCP integration for Minecraft MCP Server; refresh MCP and inspect Cascade's tools.
  • Minecraft MCP Server uses stdio here: Windsurf must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
  • Known limitation: Requires a running game and a reachable world.
  • Known limitation: The compatibility notice warns that versions newer than 1.21.11 may not work.
  • Known limitation: Desktop client startup can take time.
  • General Windsurf troubleshooting lives in the /clients/windsurf guide.

Minecraft MCP Server — details. Windsurf guide

Frequently asked questions

Windsurf reads Minecraft MCP Server under mcpServers in ~/.codeium/windsurf/mcp_config.json on macOS/Linux; Windows uses %USERPROFILE%\.codeium\windsurf\mcp_config.json.

Windsurf's minecraft-mcp-server example uses stdio.

Minecraft MCP Server's Windsurf configuration invokes npx (Node.js/npm).

Minecraft MCP Server's stored list contains 18 tools, including get-position, move-to-position, look-at. Compare those names with Windsurf's connected tool list; the stored list is not a live check.

Yes. The README's workflow opens that world to LAN so the bot can connect.

Yes. Tools cover blocks, inventory, smelting, entities, game-mode detection, and chat.