YetAnotherUnityMcp CLAUDE.md

CLAUDE.md - Development Guidelines

Project Overview

YetAnotherUnityMcp is a system that bridges the Unity game engine with AI-driven tools using the Model Context Protocol (MCP):

• Unity MCP Plugin (Client): A C# plugin integrated into the Unity Editor that connects to the MCP server via WebSockets
• FastMCP Python Server: A Python application that implements the MCP interface for Unity
• MCP Client (AI or External): The external entity (such as an AI assistant or testing script) that sends MCP requests

This architecture cleanly separates the game engine concerns from the AI logic, improving scalability and maintainability. The goal is to allow AI agents to inspect and control a running Unity scene in a structured, safe manner.

Model Context Protocol (MCP)

We use FastMCP for MCP integration, which provides:

• Simple decorator-based API for creating MCP servers
• Support for Resources, Tools, and Prompts
• Standard MCP primitives for AI interaction with Unity
• Integration with Claude Desktop via fastmcp CLI tool

Commands

# Server (Python)
cd server
python -m pip install -e ".[dev]"     # Install with dev dependencies
python -m uvicorn main:app --reload   # Run the traditional server with auto-reload
python -m pytest                      # Run all tests
python -m pytest test_file.py         # Run a specific test file
python -m pytest test_file.py::test_func # Run a single test
python -m black .                     # Format Python code
python -m flake8                      # Lint Python code
python -m mypy .                      # Type-check Python code

# MCP Integration 
source $HOME/.local/bin/env           # Set up uv environment
python -m server.mcp_server           # Run MCP server from command line
python -m server.fastmcp_example      # Run simplified FastMCP example

# MCP Development
fastmcp dev server/mcp_server.py           # Run with MCP Inspector UI
fastmcp dev server/fastmcp_example.py      # Test simplified example

# Claude Desktop Installation
fastmcp install server/mcp_server.py       # Install in Claude Desktop
fastmcp install server/fastmcp_example.py --name "Unity Simple" # Install simplified version
fastmcp install server/mcp_server.py -e UNITY_PATH=/path/to/unity # With environment variables

# Plugin (C#)
# Build and install Unity plugin via Unity Editor