connectToServer

Establish a connection to a Minecraft server using host address, username, and optional credentials to enable remote control and interaction.

Instructions

Connect to a Minecraft server with the specified credentials

Input Schema

TableJSON Schema

Name	Required	Description
`host`	Yes	Minecraft server host address
`port`	No	Minecraft server port
`username`	Yes	Minecraft username
`password`	No	Minecraft password (if using premium account)
`version`	No	Minecraft version

Implementation Reference

src/tools/connect.ts:37-95 (handler)

The handler function that implements the connectToServer tool logic: checks current connection state, creates a mineflayer bot instance with provided credentials, loads pathfinder plugin, and sets up event listeners for spawn, error, and timeout.

async ({ host, port, username, password, version }) => {
  if (botState.isConnected && botState.bot) {
    return createAlreadyConnectedResponse()
  }

  try {
    updateConnectionInfo({
      host,
      port,
      username,
      version: version || 'auto',
    })

    // Bot connection options
    const options = {
      host,
      port,
      username,
      password,
      version,
    }

    // Create the bot
    const bot = createBot(options)

    // Add pathfinder plugin to the bot
    bot.loadPlugin(pathfinder)

    return new Promise<ToolResponse>((resolve) => {
      // When login is successful
      bot.once('spawn', () => {
        updateConnectionState(true, bot)
        resolve(
          createSuccessResponse(
            `Successfully connected to ${host}:${port} as ${username}`
          )
        )
      })

      // When an error occurs
      bot.once('error', (err) => {
        updateConnectionState(false, null)
        resolve(createErrorResponse(err))
      })

      // Timeout handling (if connection is not established after 10 seconds)
      setTimeout(() => {
        if (!botState.isConnected) {
          updateConnectionState(false, null)
          resolve(
            createSuccessResponse('Connection timed out after 10 seconds')
          )
        }
      }, 10000)
    })
  } catch (error) {
    return createErrorResponse(error)
  }
}

src/tools/connect.ts:23-36 (schema)

Zod schema defining the input parameters for the connectToServer tool: host (required string), port (optional number default 25565), username (required string), password (optional string), version (optional string).

{
  host: z.string().describe('Minecraft server host address'),
  port: z
    .number()
    .optional()
    .default(25565)
    .describe('Minecraft server port'),
  username: z.string().describe('Minecraft username'),
  password: z
    .string()
    .optional()
    .describe('Minecraft password (if using premium account)'),
  version: z.string().optional().describe('Minecraft version'),
},

src/tools/connect.ts:20-96 (registration)

Direct registration of the connectToServer tool using server.tool(), including name, description, input schema, and handler function.

server.tool(
  'connectToServer',
  'Connect to a Minecraft server with the specified credentials',
  {
    host: z.string().describe('Minecraft server host address'),
    port: z
      .number()
      .optional()
      .default(25565)
      .describe('Minecraft server port'),
    username: z.string().describe('Minecraft username'),
    password: z
      .string()
      .optional()
      .describe('Minecraft password (if using premium account)'),
    version: z.string().optional().describe('Minecraft version'),
  },
  async ({ host, port, username, password, version }) => {
    if (botState.isConnected && botState.bot) {
      return createAlreadyConnectedResponse()
    }

    try {
      updateConnectionInfo({
        host,
        port,
        username,
        version: version || 'auto',
      })

      // Bot connection options
      const options = {
        host,
        port,
        username,
        password,
        version,
      }

      // Create the bot
      const bot = createBot(options)

      // Add pathfinder plugin to the bot
      bot.loadPlugin(pathfinder)

      return new Promise<ToolResponse>((resolve) => {
        // When login is successful
        bot.once('spawn', () => {
          updateConnectionState(true, bot)
          resolve(
            createSuccessResponse(
              `Successfully connected to ${host}:${port} as ${username}`
            )
          )
        })

        // When an error occurs
        bot.once('error', (err) => {
          updateConnectionState(false, null)
          resolve(createErrorResponse(err))
        })

        // Timeout handling (if connection is not established after 10 seconds)
        setTimeout(() => {
          if (!botState.isConnected) {
            updateConnectionState(false, null)
            resolve(
              createSuccessResponse('Connection timed out after 10 seconds')
            )
          }
        }, 10000)
      })
    } catch (error) {
      return createErrorResponse(error)
    }
  }
)

src/tools/index.ts:17-17 (registration)
Invocation of registerConnectTools() within the registerAllTools() function to register connection-related tools.
```
registerConnectTools()
```
src/index.ts:7-7 (registration)
Top-level call to registerAllTools() which indirectly registers the connectToServer tool.
```
registerAllTools()
```

MCP Minecraft Remote