Hyperfy MCP Server

An MCP (Model Context Protocol) server that provides integration with Hyperfy game worlds through WebSocket connections and API endpoints.

Features

• Real-time Game Integration: Connect to running Hyperfy game servers via WebSocket
• JWT Authentication: Seamless authentication using the same JWT secret as the game server
• Entity Management: Query, add, modify, and remove entities in the game world
• Player Interaction: Get player information, send chat messages, execute commands
• Blueprint Access: Access and manage game blueprints
• Real-time Updates: Receive live updates about game state changes

Installation

1. Navigate to the mcp-server directory:

cd mcp-server

2. Install dependencies:

npm install

3. Copy and configure environment variables:

cp .env.example .env
# Edit .env with your Hyperfy server configuration

4. Build the TypeScript code:

npm run build

Configuration

Create a .env file with the following variables:

# Hyperfy Game Server Configuration
HYPERFY_WS_URL=ws://localhost:3000/ws
HYPERFY_API_URL=http://localhost:3000/api
HYPERFY_JWT_SECRET=hyper

# MCP Server Configuration  
MCP_SERVER_PORT=3001
MCP_SERVER_NAME=hyperfy-game-integration

# Optional: Custom player configuration for MCP connections
MCP_PLAYER_NAME=MCP-Assistant
MCP_PLAYER_AVATAR=

# Debug settings
DEBUG=false

Usage

Start the MCP Server

npm start

Development Mode

npm run dev

Available Tools

The MCP server provides the following tools:

Connection Management

• connect_to_game: Connect to the Hyperfy game server
• get_game_status: Get current connection status and basic game information

Entity Management

• get_entities: Get all entities in the game world (with optional type filtering)
• get_entity: Get a specific entity by ID
• add_entity: Add a new entity to the game world (requires builder permissions)
• modify_entity: Modify an existing entity (requires appropriate permissions)
• remove_entity: Remove an entity from the game world (requires builder permissions)

Player Interaction

• get_players: Get all players currently in the game world
• send_chat_message: Send a chat message to the game
• get_chat_history: Get recent chat messages from the game
• execute_command: Execute a slash command in the game (admin/builder permissions may be required)

Blueprints

• get_blueprints: Get all available blueprints in the game

Integration with Claude Code

To use this MCP server with Claude Code, add the following to your .mcp.json configuration:

{
  "mcpServers": {
    "hyperfy": {
      "command": "node",
      "args": ["./mcp-server/dist/index.js"]
    }
  }
}

Architecture

The MCP server consists of several key components:

HyperfyGameClient (game-client.ts)

• Manages WebSocket connection to the Hyperfy game server
• Handles authentication using JWT tokens
• Processes real-time game events and maintains local state
• Provides methods for game interactions

HyperfyMCPServer (mcp-server.ts)

• Implements the MCP protocol using @modelcontextprotocol/sdk
• Exposes game functionality as MCP tools
• Handles tool requests and responses
• Manages the game client connection

Authentication (auth.ts)

• JWT token creation and verification
• User ID generation for MCP connections
• Compatible with Hyperfy's authentication system

Packet Protocol (packets.ts)

• Encoding/decoding of Hyperfy's WebSocket packet format
• Binary data handling for real-time communication

Permissions

Different operations require different permission levels in Hyperfy:

• Visitor: Can view entities, players, chat history
• Builder: Can add, modify, and remove entities; send chat messages
• Admin: Can execute admin commands, manage players

The MCP server connects as a regular player and inherits the permissions of the configured user account.

Error Handling

The server includes comprehensive error handling:

• Automatic reconnection on WebSocket disconnections
• Graceful handling of authentication failures
• Detailed error messages for tool operations
• Debug logging for troubleshooting

Development

Project Structure

mcp-server/
├── src/
│   ├── index.ts          # Main entry point
│   ├── mcp-server.ts     # MCP server implementation
│   ├── game-client.ts    # Hyperfy game client
│   ├── auth.ts           # JWT authentication
│   ├── packets.ts        # Packet encoding/decoding
│   ├── config.ts         # Configuration loading
│   └── types.ts          # TypeScript type definitions
├── dist/                 # Compiled JavaScript output
├── package.json          # Node.js package configuration
├── tsconfig.json         # TypeScript configuration
└── README.md            # This file

Building

npm run build

Watching for Changes

npm run watch

License

GPL-3.0-only (same as Hyperfy)