How to Connect Blender with Google Antigravity Using MCP: Complete Setup Guide

Imagine describing a 3D model in plain English and having an AI agent create it directly inside Blender. You could ask for a realistic vehicle, a detailed building, a human anatomical model, or an animated environment without manually performing every modeling operation.

By connecting Blender to Google Antigravity through the Model Context Protocol (MCP), you can give an AI agent access to tools that interact with Blender. Depending on the tools available, the agent can create objects, assign materials, execute Blender Python code, render previews, inspect scenes, and export assets.

In this guide, we will explain how to set up Blender MCP Antigravity integration on macOS, configure the connection, verify that it works, and troubleshoot common problems.

We will also explore how to use the connection to test AI-generated 3D models, including anatomically realistic adult human figures and game-ready assets.

What Is Blender MCP?

The Model Context Protocol, commonly known as MCP, is a standard that allows AI applications to interact with external tools and services.

Blender MCP connects an MCP-compatible AI client to Blender through a bridge. Instead of merely generating instructions for you to follow, the AI can invoke tools exposed by the MCP server to perform operations in Blender.

For this guide, we use the community project Blender MCP by mackson on GitHub.

The project describes a TypeScript MCP server that communicates with a Python add-on inside Blender through a WebSocket connection.

How the connection works

The integration has three main components:

1. Google Antigravity: The AI development environment where you describe the work you want completed.
2. Blender MCP server: A Node.js application that exposes Blender-related tools to the AI client.
3. Blender add-on: A Python component that receives supported operations and interacts with Blender’s Python API.

The communication flow looks like this:

Antigravity → MCP server over standard input/output → WebSocket bridge → Blender add-on → Blender scene

The MCP server typically runs as a child process launched by Antigravity. Blender runs separately, with its add-on listening for incoming connections.

What can you do with this integration?

Depending on the installed version and available tools, you can use natural-language instructions to:

• Create and modify 3D objects.
• Apply materials and textures.
• Generate procedural objects and environments.
• Execute custom Blender Python operations.
• Create architectural concepts and vehicle models.
• Render preview images.
• Inspect and refine a scene.
• Export supported formats such as GLB, FBX, and OBJ.
• Produce assets for game engines and Three.js applications.

Important: MCP provides tool access; it does not guarantee that every requested model will be accurate or production-ready. The quality depends on the modeling workflow, the AI’s decisions, the tools available, and the amount of refinement performed.

Read also: AI Image Enhancement Prompts: Transform Any Photo Into a Professional Cinematic Image

Requirements Before You Begin

Install the required software before configuring the connection.

Component	Requirement
Blender	Version 4.0 or newer is specified by the project documentation; verify compatibility with your installed add-on
Node.js	Node.js 20 or newer is a sensible baseline for this setup; check the repository’s current requirements
npm	Installed with Node.js
Google Antigravity	A version that supports custom MCP servers
Git	Required to clone the repository
Blender MCP project	The community repository linked in this guide

Download Blender from blender.org and Node.js from nodejs.org.

Check whether Node.js, npm, and Git are installed by running these commands in Terminal on macOS or Linux:

node --version
npm --version
git --version

If the commands return version numbers, the corresponding programs are available in your terminal environment.

Check the Node.js executable path as well:

which node

You will use the full path returned by this command in the Antigravity MCP configuration.

Step 1: Download the Blender MCP Repository

Open Terminal and navigate to a directory where you keep development projects.

For example:

mkdir -p ~/Developer
cd ~/Developer

Clone the repository:

git clone https://github.com/mackson/blender-mcp.git blender-mcp-v2

Enter the downloaded project directory:

cd ~/Developer/blender-mcp-v2

Inspect the files:

ls -la

The repository should contain files such as README.md, USAGE.md, and the src directory.

You can also inspect the relevant folders:

ls -la src
ls -la src/mcp-server

Repository note: Follow the file structure of the version you actually downloaded. Repository documentation and older installation examples can contain different paths. Do not assume that a placeholder repository URL or an outdated file location is valid.

Step 2: Install the MCP Server Dependencies

Move into the MCP server directory:

cd ~/Developer/blender-mcp-v2/src/mcp-server

Install the dependencies:

npm install

Build the project:

npm run build

The build should generate compiled JavaScript files in the dist directory.

Verify that the main entry point exists:

ls -la ~/Developer/blender-mcp-v2/src/mcp-server/dist

Look for:

index.js
server.js

Other files and subdirectories may also appear.

Why use npm install instead of npm ci?

These commands serve related but different purposes.

• npm install installs the dependencies specified by the project and can generate a package lockfile when needed.
• npm ci performs a clean, reproducible installation and requires a compatible existing package-lock.json or npm-shrinkwrap.json.

If you receive an error stating that npm ci requires a lockfile, inspect the directory and use the installation command appropriate to the repository.

Do not run npm commands from an unrelated folder. The MCP server’s package.json should be present in the directory where you execute them.

Step 3: Locate the Blender Python Add-on

The next step is to install the Python add-on that connects Blender to the MCP server.

For the repository structure used in this guide, the add-on path is:

blender-mcp-v2/src/blender-addon/mcp_connector_v2.py

Confirm the file exists by running:

find ~/Developer/blender-mcp-v2 -name "mcp_connector_v2.py"

The command should return the actual location of the file.

If it returns nothing, inspect the repository’s README and usage guide. Do not continue using a guessed path.

Step 4: Install the Add-on in Blender

Open Blender and follow these steps:

1. Open Edit → Preferences.
2. Navigate to the add-ons or extension installation section supported by your Blender version.
3. Click the installation option.
4. Browse to mcp_connector_v2.py.
5. Select the file and install it.
6. Enable the add-on named Interface: MCP Connector v2, or the corresponding name shown by the installed version.
7. Save the preferences if the interface offers that option.

The precise wording and location of add-on controls may differ between Blender releases.

Start the Blender MCP server

After enabling the add-on:

1. Open the 3D Viewport.
2. Press N to display the sidebar.
3. Find the MCP tab.
4. Click Start Server.
5. Confirm that the add-on reports that the server is running.

The documented default WebSocket endpoint is:

ws://127.0.0.1:9876

Some configurations may display 0.0.0.0 as the listening address. That indicates a listening interface rather than the address the local MCP client necessarily needs to use.

Keep Blender running while you test the connection.

Step 5: Configure Google Antigravity

Antigravity needs to know how to launch the Node.js MCP server.

For current Antigravity global MCP configuration, the file is:

~/.gemini/config/mcp_config.json

Google’s documentation also describes workspace-level configuration using .agents/mcp_config.json. The global configuration is appropriate when you want the Blender connection available across projects.

Create the global configuration directory if necessary:

mkdir -p ~/.gemini/config

Open the configuration file:

nano ~/.gemini/config/mcp_config.json

Add the following entry, replacing the example paths with the actual paths on your machine:

{
  "mcpServers": {
    "blender-mcp": {
      "command": "/opt/homebrew/bin/node",
      "args": [
        "/Users/YOUR_USERNAME/Developer/blender-mcp-v2/src/mcp-server/dist/index.js"
      ],
      "env": {
        "BLENDER_HOST": "127.0.0.1",
        "BLENDER_PORT": "9876",
        "LOG_LEVEL": "info"
      }
    }
  }
}

There are two important path substitutions.

First: Node.js executable

Run:

which node

Replace /opt/homebrew/bin/node with the path returned by your system.

Second: MCP server entry point

Replace YOUR_USERNAME and the project path with the actual location of dist/index.js.

Use absolute paths rather than relying on the current working directory. This avoids problems when Antigravity launches the server from a different directory.

Preserve existing MCP servers

If your configuration already contains other integrations, do not replace the entire file with the example.

Instead, add the blender-mcp object alongside the existing entries within mcpServers. Each server name must be unique, and the JSON must remain valid.

For example, a configuration containing two servers would look like this:

{
  "mcpServers": {
    "existing-server": {
      "command": "existing-command",
      "args": []
    },
    "blender-mcp": {
      "command": "/opt/homebrew/bin/node",
      "args": [
        "/Users/YOUR_USERNAME/Developer/blender-mcp-v2/src/mcp-server/dist/index.js"
      ],
      "env": {
        "BLENDER_HOST": "127.0.0.1",
        "BLENDER_PORT": "9876",
        "LOG_LEVEL": "info"
      }
    }
  }
}

This is a structural example. Keep the real command, arguments, and environment variables for every existing server.

Save the configuration

If you are using Nano:

1. Press Ctrl+O to write the file.
2. Press Enter to confirm the filename.
3. Press Ctrl+X to exit.

Validate the JSON

Run this command:

node -e 'JSON.parse(require("fs").readFileSync(process.env.HOME + "/.gemini/config/mcp_config.json", "utf8")); console.log("MCP config JSON is valid")'

Expected output:

MCP config JSON is valid

This validates the JSON syntax. It does not prove that Antigravity can launch the server or communicate with Blender.

Step 6: Reload Antigravity and Register the Server

After saving the configuration:

1. Completely quit Antigravity.
2. Reopen the application.
3. Open the Agent panel.
4. Navigate to the MCP server management interface.

In Antigravity versions with the documented interface, the path is:

Agent panel menu → MCP Servers → Manage MCP Servers → View raw config

Another route in newer versions may be:

Settings → Customizations → Installed MCP Servers

Google’s official documentation describes both MCP configuration and server management in its MCP guide.

Look for blender-mcp in the server list. If the interface provides a refresh control, use it after saving the configuration.

If you cannot find the MCP menu, do not assume the server is broken. Check the documentation for your installed Antigravity version and verify that you are using the correct configuration file.

Step 7: Verify the MCP Server Starts

Before testing the complete connection, you can launch the MCP server manually.

Open Terminal and run:

cd ~/Developer/blender-mcp-v2/src/mcp-server
node dist/index.js

A successful startup may produce messages similar to:

Blender MCP Server starting...
Blender endpoint: ws://127.0.0.1:9876
Creating MCP server...
Registering tools...
Tools registered {"count":17}
MCP server created successfully
Connecting to stdio transport...
MCP server is running and ready for requests

The exact wording depends on the installed version.

A process that remains running and prints these messages indicates that the MCP server has initialized. Because this is a standard-input/output MCP process, it may wait for client requests without displaying additional output.

However, successful startup alone does not prove that Antigravity has registered the tools or that Blender is connected.

Press Ctrl+C to stop a manually launched test before allowing Antigravity to start its own server instance.

Do not run a second copy of the MCP process unnecessarily while troubleshooting the connection.

Step 8: Verify the Blender Connection

Make sure Blender is open and the add-on server is running.

In a new Antigravity conversation, send this prompt:

Check Blender connection status using the blender-mcp status tool. Report whether Blender is connected, the Blender version, the add-on version, and the active scene. Do not modify the scene yet.

A successful response should report that the connection is active and provide the available version and scene information.

The exact response format depends on the MCP server implementation.

The project documents a status tool for connection checks. Its other tools cover scene inspection, object creation, materials, rendering, export, procedural generation, and other operations.

If the status tool is unavailable, return to Antigravity’s MCP server settings and inspect the server’s registration status and logs.

Step 9: Create Your First 3D Object

Once the connection is confirmed, start with a small and reversible test.

Use this prompt:

Use the connected blender-mcp tools to create a red metallic cube named MCP_Test_Cube inside Blender. Add a ground plane and a camera. Apply a red metallic material, create suitable lighting, and render a preview. Save the actual project as mcp_test.blend in a designated output folder. Confirm the saved path and report any errors.

Inspect the result in Blender.

Check that:

• The cube exists in the scene.
• The material is assigned.
• The camera and lights are present.
• The render completes.
• The project file is actually saved.

This basic test separates connection problems from more complicated modeling problems.

Step 10: Test Advanced 3D Modeling Precision

After basic object creation works, use more demanding prompts to assess how well the AI controls Blender.

Test A: Create a realistic human anatomical model

For a detailed anatomical modeling test, ask Antigravity to create an anatomically realistic adult human figure in a neutral A-pose.

Specify:

• Accurate overall body proportions.
• Detailed face, hands, fingers, feet, and joints.
• Natural transitions between body regions.
• A coherent mesh rather than visibly assembled primitive shapes.
• Suitable topology and surface normals.
• Neutral studio lighting and multiple camera angles.
• Inspection and correction of visible defects.
• Native Blender project and GLB export.

If the goal is anatomical visualization, explicitly request a non-sexualized educational model and appropriate anatomical detail.

Do not assume that an AI-generated human model will automatically have accurate anatomy or clean topology. Inspect the result from the front, side, and rear, then examine the face, hands, feet, and joints closely.

Test B: Compare male and female anatomy

You can create separate adult male and female anatomical models using the same camera positions, scale, and lighting setup.

This makes it easier to compare:

• Overall proportions and silhouettes.
• Pelvis and torso structure.
• Shoulder and limb proportions.
• Facial geometry.
• Hand and foot anatomy.
• Mesh continuity and surface quality.

Save each project separately to prevent accidental overwriting.

Test C: Create a game-ready vehicle

Try this prompt:

Create a low-poly sports car suitable for a Three.js game. Use clean geometry, realistic proportions, separate wheels, suitable materials, and a consistent scale. Inspect the model for obvious intersections and export it as a GLB file. Confirm the export path and report any limitations.

This is useful for developers who want to use Blender MCP to generate assets for browser-based 3D games.

Test D: Create a small environment

Ask Antigravity to create a road segment, surrounding buildings, streetlights, trees, and a camera.

Request consistent object scale, reusable assets, optimized geometry, and suitable materials. Inspect the scene before exporting it.

These tests reveal whether the integration can handle progressively more complex work.

Step 11: Export Blender Models for Three.js

Blender MCP can expose export functionality for formats such as GLB, FBX, and OBJ.

For web-based 3D projects, GLB is often a convenient choice because it can package mesh data, materials, textures, and supported animation data into a single binary file.

After creating a model, use a prompt such as:

Export the finished model as a GLB file. Include the required mesh data, materials, textures, and supported animations. Verify that the export file exists and report its full path.

Then load the asset into a Three.js project using GLTFLoader.

A typical JavaScript example is:

import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';

const loader = new GLTFLoader();

loader.load(
  '/models/example.glb',
  (gltf) => {
    scene.add(gltf.scene);
  },
  undefined,
  (error) => {
    console.error('Failed to load GLB model:', error);
  }
);

The example assumes that Three.js and its loader are already configured in your project.

Always test exported assets in the target application. Materials, texture paths, animation features, and other data can behave differently between Blender and the destination runtime.

Troubleshooting: Common Blender MCP Problems

Even if the installation is correct, configuration, process startup, or local networking can prevent the connection from working.

Problem 1: GitHub authentication failed

You may see:

remote: Invalid username or token.
Password authentication is not supported for Git operations.
fatal: Authentication failed

This often occurs when an incorrect repository URL is used or GitHub HTTPS authentication is attempted with an account password.

Check the repository URL:

git ls-remote https://github.com/mackson/blender-mcp.git

If the repository is publicly accessible, this command should not normally require your GitHub password.

If you still receive an authentication error, check your Git credential configuration and confirm the URL. Do not enter your GitHub password as a substitute for a supported authentication method.

Problem 2: cd: no such file or directory

Example:

cd: no such file or directory: blender-mcp-v2/src/mcp-server

This means the target directory does not exist relative to your current location.

Check the project directory:

ls -la ~/Developer/blender-mcp-v2

Then inspect the server directory:

ls -la ~/Developer/blender-mcp-v2/src/mcp-server

If the clone failed, fix that problem before running additional commands.

Problem 3: npm ci reports that the lockfile is missing

Example:

npm error The npm ci command can only install with an existing package-lock.json

Change to the directory containing the MCP server’s package.json:

cd ~/Developer/blender-mcp-v2/src/mcp-server

Then run:

npm install
npm run build

Use npm ci when the repository contains the required lockfile and you want a clean, reproducible installation.

Problem 4: npm cannot find package.json

Example:

npm error enoent Could not read package.json

You are likely running npm from the wrong directory.

Find the project files:

find ~/Developer/blender-mcp-v2 -name package.json

Navigate to the appropriate server directory and rerun the command.

Problem 5: The Blender add-on does not appear

Check that the Python file exists:

find ~/Developer/blender-mcp-v2 -name "mcp_connector_v2.py"

Install the exact file returned by the command, not the containing folder.

Verify that the add-on is enabled in Blender’s preferences and that the version is compatible with your Blender release.

If the file cannot be found, inspect the README and usage instructions for the repository version you cloned.

Problem 6: Antigravity does not list blender-mcp

Start by checking the global configuration:

cat ~/.gemini/config/mcp_config.json

Validate its syntax:

node -e 'JSON.parse(require("fs").readFileSync(process.env.HOME + "/.gemini/config/mcp_config.json", "utf8")); console.log("MCP config JSON is valid")'

If the file is valid:

1. Verify that the MCP entry is under mcpServers.
2. Confirm the command path returned by which node.
3. Confirm that the args path points to the actual compiled dist/index.js.
4. Preserve existing server entries and ensure there are no duplicate keys.
5. Restart Antigravity.
6. Inspect the MCP server status and logs.

Current Antigravity documentation identifies ~/.gemini/config/mcp_config.json as the global configuration location and .agents/mcp_config.json as a workspace-level alternative. Older project instructions may refer to a legacy location, so use the path supported by your installed Antigravity version.

Problem 7: The server starts, but Blender is disconnected

Check whether the add-on is running inside Blender.

On macOS, run:

lsof -nP -iTCP:9876 -sTCP:LISTEN

If the add-on is listening on port 9876, the output should identify the process holding that port.

This confirms that a process is listening; it does not by itself establish that the MCP bridge is functioning correctly.

Next:

1. Confirm that Blender is still open.
2. Check the add-on’s status in the MCP panel.
3. Confirm that the MCP server uses 127.0.0.1 and port 9876 when connecting locally.
4. Check the Blender console for errors.
5. Restart the Blender add-on and MCP client if necessary.

Problem 8: The MCP server starts but tools do not respond

Look at the server startup output and Antigravity’s MCP logs.

The server may start correctly while its connection to Blender is unavailable. A successful process launch and successful Blender communication are two different checks.

Verify the connection using the status tool before attempting object creation.

Problem 9: connect EPERM or connection refused

A local socket error can indicate that the client cannot access the network endpoint.

Possible causes include:

• Local network permissions.
• A sandbox restricting network connections.
• An incorrect host or port.
• A stopped Blender add-on.
• A conflicting process or firewall rule.

Confirm that the configured host and port match the running add-on. Avoid exposing the WebSocket listener to the public internet simply to work around a local connection error.

Problem 10: The model looks unrealistic or has poor geometry

A working MCP connection does not guarantee a high-quality model.

If a human figure or vehicle looks inaccurate:

1. Request a blockout before detailed modeling.
2. Ask for front, side, and rear inspections.
3. Request explicit checks for intersections and malformed geometry.
4. Refine difficult areas individually.
5. Inspect topology and normals.
6. Render again after each meaningful revision.
7. Export only after verifying the result.

For complex anatomy, a single prompt may not be sufficient. A staged workflow is usually easier to inspect and improve.

Best Practices for Reliable AI-Powered Blender Workflows

Work in stages

For complex projects, separate modeling into clear stages:

1. Requirements and references.
2. Blockout and proportions.
3. Geometry refinement.
4. Materials and textures.
5. Lighting and cameras.
6. Render inspection.
7. Corrections.
8. Export and validation.

This makes it easier to identify where the AI has made a mistake.

Use precise prompts

Avoid vague requests such as “make a realistic human.”

Instead, specify dimensions, proportions, pose, surface characteristics, topology requirements, camera angles, output formats, and inspection criteria.

Save projects regularly

Ask the agent to save checkpoints during longer tasks. Use distinct filenames for different stages and avoid overwriting important projects.

Verify every deliverable

A message saying that a file was saved is not sufficient by itself.

Check that the file exists, opens in Blender, and contains the expected objects. For GLB exports, load the asset into the target application and inspect materials, textures, scale, and animation.

Keep the connection local

When Blender and Antigravity run on the same computer, the loopback address 127.0.0.1 is generally appropriate. Avoid exposing local control interfaces to untrusted networks.

Treat generated scripts carefully

The ability to execute Blender Python code is powerful. Review custom scripts and understand the operations they perform, especially when they modify files, remove scene objects, or run outside Blender.

Frequently Asked Questions

Can Antigravity create Blender files automatically?

Yes, when the configured MCP tools support the required operations. The AI can create or modify a scene and invoke saving or export operations. Always verify that the resulting files exist and contain the expected content.

Do I need to keep Blender open?

For this local add-on workflow, yes. Blender must be running with the connector enabled and its server started while the MCP client uses it.

Do I need to run node dist/index.js manually every time?

Normally, no. When correctly configured, Antigravity launches the MCP server using the configured command and arguments. Running it manually is useful for troubleshooting startup problems.

Can I use Blender MCP to create human models?

Yes. You can request anatomically detailed adult human figures, poses, materials, and multiple inspection views. However, model accuracy depends on the workflow and available tools; it should not be assumed to match professional anatomy or animation standards without validation.

Can Blender MCP export assets for Three.js?

The project documents export tools for formats including GLB. GLB is generally convenient for Three.js, but you should verify that the export preserves the features required by your application.

Why does the server start successfully but Antigravity cannot use it?

The Node.js process may initialize correctly without being registered by Antigravity. Alternatively, Antigravity may register the tools while the Blender add-on is disconnected. Check both MCP registration and the Blender connection separately.

Is the integration free?

Blender is free and open source, and the linked community repository is published under an MIT license according to its project documentation. Other costs may depend on your AI service, development environment, or additional tools.

Can I use the same connection for every Blender project?

Yes. A global MCP configuration can make the server available across projects, provided the paths remain valid and Blender’s add-on is running. Workspace-level configurations may be preferable for project-specific setups.

Conclusion

Connecting Blender to Google Antigravity through MCP can make AI-assisted 3D modeling much more interactive. Instead of only generating modeling instructions, the AI can invoke tools that operate on an actual Blender scene.

The key is to configure the three components correctly: the Node.js MCP server, the Blender Python add-on, and Antigravity’s MCP configuration.

Start with a simple object, verify the connection, and then move to more demanding projects such as anatomical models, vehicles, and environments. Inspect geometry and saved files instead of relying only on the agent’s completion message.

For developers creating browser-based 3D applications, this workflow can also provide a useful path from natural-language modeling requests to Blender projects and exported GLB assets.

Useful resources

• Blender — Official Download
• Node.js — Official Website
• Blender MCP — GitHub Repository
• Blender MCP — Usage Guide
• Google Antigravity — MCP Documentation
• Three.js — Official Documentation