MCP for Unity Server

9.6.6 · active · verified Thu Apr 16

MCP for Unity Server is a Python library that provides the server-side implementation for the Model Context Protocol (MCP), enabling seamless integration and communication with Unity clients. It facilitates real-time data exchange and command execution between Python applications and the Unity Editor. The current version is 9.6.6, and it sees regular updates, often with significant architectural changes between major versions.

Common errors

```
AttributeError: 'Server' object has no attribute 'message_id'
```
cause The `message_id` field was deprecated and removed from all message types in version 9.0.0 as it was unused.

fix Remove any code that attempts to access or set the `message_id` attribute on server or client objects, or messages.
```
TypeError: object NoneType can't be used in 'await' expression (for callbacks) OR RuntimeWarning: coroutine 'your_callback' was never awaited
```
cause Prior to v8.0.0, synchronous callbacks were supported. From v8.0.0 onwards, all callbacks are expected to be asynchronous (coroutines).

fix Ensure that any function registered as a callback (e.g., for `on_connect`, `on_message`) is defined using `async def`.
```
ImportError: cannot import name 'UnityClient' from 'mcpforunityserver' (/path/to/mcpforunityserver/__init__.py)
```
cause Many common classes and types, including `UnityClient`, `ServerConfig`, and `Message`, were reorganized into the `mcpforunityserver.types` submodule in version 9.6.0.

fix Change your import statement from `from mcpforunityserver import UnityClient` to `from mcpforunityserver.types import UnityClient`.

Warnings

breaking The constructor signatures for `Server` and `UnityClient` classes, along with their associated parameters, underwent significant changes. Additionally, the `message_id` field was removed from all message types.
Fix: Review the latest documentation or source code for `Server` and `UnityClient` constructors. Update parameter names and types. Remove any reliance on `message_id` from message processing logic.
breaking The library's callback system was refactored to be exclusively asynchronous. All event handlers and callbacks must now be defined as `async def` functions and awaited if they perform asynchronous operations.
Fix: Migrate all existing synchronous callback functions to `async def` functions. Ensure that any calls to these callbacks are properly `await`ed where applicable.
gotcha Key types and core classes (e.g., `UnityClient`, `ServerConfig`, `Message`) were moved from the top-level `mcpforunityserver` package directly into the `mcpforunityserver.types` submodule for better organization.
Fix: Update import statements from `from mcpforunityserver import MyType` to `from mcpforunityserver.types import MyType` for all affected symbols.

Install

pip install mcpforunityserver Install stable version

Imports

Server
```
from mcpforunityserver import Server
```
UnityClient
wrong:
```
from mcpforunityserver import UnityClient
```
correct:
```
from mcpforunityserver.types import UnityClient
```
Types and core classes like UnityClient, ServerConfig, and Message were moved to the 'types' submodule in v9.6.0.
Message
wrong:
```
from mcpforunityserver import Message
```
correct:
```
from mcpforunityserver.types import Message
```
Types and core classes like UnityClient, ServerConfig, and Message were moved to the 'types' submodule in v9.6.0.

Quickstart

This quickstart demonstrates how to initialize and start an MCP server, setting up basic connection and disconnection event handlers. The server listens on port 25001 and remains active indefinitely.

import asyncio
from mcpforunityserver import Server

async def main():
    server = Server(
        port=25001,
        server_name='MyUnityServer',
        server_version='1.0.0'
    )
    
    @server.on_connect
    async def handle_connect(client):
        print(f'Client connected: {client.id}')

    @server.on_disconnect
    async def handle_disconnect(client):
        print(f'Client disconnected: {client.id}')

    await server.start()
    print(f'MCP Server started on port {server.port}')
    
    # Keep the server running indefinitely
    while True:
        await asyncio.sleep(3600) # Sleep for an hour

if __name__ == '__main__':
    asyncio.run(main())

view raw JSON →