MCP server for Hyperfy game integration
npm install hyperfy-mcp-serverAn MCP (Model Context Protocol) server that provides integration with Hyperfy game worlds through WebSocket connections and API endpoints.
- 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
1. Navigate to the mcp-server directory:
``bash`
cd mcp-server
2. Install dependencies:
`bash`
npm install
3. Copy and configure environment variables:
`bash`
cp .env.example .envEdit .env with your Hyperfy server configuration
4. Build the TypeScript code:
`bash`
npm run build
Create a .env file with the following variables:
`envHyperfy Game Server Configuration
HYPERFY_WS_URL=ws://localhost:3000/ws
HYPERFY_API_URL=http://localhost:3000/api
HYPERFY_JWT_SECRET=hyper
Usage
$3
`bash
npm start
`$3
`bash
npm run dev
`$3
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 gameIntegration with Claude Code
To use this MCP server with Claude Code, add the following to your
.mcp.json configuration:`json
{
"mcpServers": {
"hyperfy": {
"command": "node",
"args": ["./mcp-server/dist/index.js"]
}
}
}
`Architecture
The MCP server consists of several key components:
$3
- 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$3
- Implements the MCP protocol using @modelcontextprotocol/sdk
- Exposes game functionality as MCP tools
- Handles tool requests and responses
- Manages the game client connection$3
- JWT token creation and verification
- User ID generation for MCP connections
- Compatible with Hyperfy's authentication system$3
- Encoding/decoding of Hyperfy's WebSocket packet format
- Binary data handling for real-time communicationPermissions
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
$3
`
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
`$3
`bash
npm run build
`$3
`bash
npm run watch
``GPL-3.0-only (same as Hyperfy)