Blender MCP TypeScript Server

A TypeScript implementation of the Blender Model Context Protocol (MCP) server with Server-Sent Events (SSE) support.

Features

• TypeScript implementation with full type safety
• SSE-based communication with MCP clients
• Socket-based communication with Blender
• Built-in tools:
  • get_scene_info: Get detailed information about the current Blender scene
  • execute_blender_code: Execute Python code in Blender
  • PolyHaven Integration:
    • get_polyhaven_categories: Get available categories for a specific type of PolyHaven asset
    • search_polyhaven_assets: Search for assets on PolyHaven with optional category filtering
    • download_polyhaven_asset: Download and import a PolyHaven asset into Blender
    • set_texture: Apply a downloaded PolyHaven texture to an object
    • get_polyhaven_status: Check if PolyHaven integration is enabled

Prerequisites

• Node.js 16.x or later
• Blender with the MCP addon installed and running
• npm or yarn package manager

Installation

1. Clone the repository
2. Install dependencies:

   npm install

3. Build the project:

   npm run build

Usage

1. Start the server:

   # Using default ports
   npm start
   
   # Using custom ports via environment variables
   PORT=8000 CONNECTOR_PORT=9000 npm start
   
   # Using custom ports via command line arguments
   npm start -- --port=8000 --connector-port=9000

   The server will start with the configured ports based on the priority order mentioned above.

   Using PolyHaven Tools:

   • Ensure that the PolyHaven integration is enabled.
   • Use the provided tools to interact with PolyHaven assets as needed.

• PolyHaven Integration: Ensure that the PolyHaven integration is enabled if you plan to use these features.

Development

To run the server in development mode with automatic recompilation:

npm run dev

Environment Variables

• CONNECTOR_PORT: The port number for Blender connection (default: 9025)

Connection Details

The server uses two configurable ports:

1. MCP Server Port: Listens for client connections (default: 7451)
2. Blender Connector Port: Connects to Blender (default: 9025)

These ports can be configured through:

1. Environment variables (MCP_PORT, CONNECTOR_PORT)
2. Command line arguments (--port=<number>, --connector-port=<number>)
3. Default values if neither is specified

Priority order: Environment Variables > Command Line Arguments > Default Values

Architecture

The server consists of three main components:

1. BlenderConnection: Handles socket communication with Blender, connecting to localhost on the configured connector port (default: 9025).
2. BlenderMcpServer: Implements the MCP server with SSE support on the configured MCP port (default: 7451), providing tools for scene information and code execution.
3. Main Entry Point (index.ts): Initializes the server components with configurable ports through environment variables or command line arguments, following a priority-based configuration system.

Acknowledgments

This project is based on the original work by Siddharth Ahuja, as found on GitHub. We appreciate their contributions to the development of the Blender MCP server.

License

MIT