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:
``bash
cd mcp-server
`

2. Install dependencies:
`bash
npm install
`

3. Copy and configure environment variables:
`bash
cp .env.example .env


Edit .env with your Hyperfy server configuration


`

4. Build the TypeScript code:
`bash
npm run build
`

Configuration

Create a .env file with the following variables:

`env


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

$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 game

Integration 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 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

$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
``

License

GPL-3.0-only (same as Hyperfy)