> For the complete documentation index, see [llms.txt](https://docs.m-xr.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.m-xr.com/marso-studio/plugins/m-xr-plugins/blender-with-your-ai-agent.md). # Blender with your AI agent Your AI agent models the object in Blender, part by part. You give it a new look from your prompt with Retexture, in the Marso panel, and Marso adds predicted PBR materials to every part. Then your agent lights it, renders it and shows you the result in the chat. Set it up once, in the order below. Then see [Make something](#make-something) and [Get the best results](#get-the-best-results). ## What you'll need * **Blender 5.2 or newer.** * **A Marso Studio account on a paid plan or the trial.** Marso MCP and the Marso add-on work through the Marso Studio API, which the Free plan doesn't include. See [Plans](/marso-studio/reference/credits-and-billing.md#plans). * **An agent app that can run MCP servers on your computer:** Claude Desktop, Claude Code or Codex. * **Credits** for Retexture and PBR. Modelling, lighting and rendering in Blender spend none. See [Credits & billing](/marso-studio/reference/credits-and-billing.md). ## Set it up ### 1. Create a Marso API key 1. Log in to [marso.app](https://marso.app/). 2. Open **API Keys** in the left sidebar. 3. Under **New Key**, give the key a name ("Blender" is a sensible one) and click **Create Key**. 4. **Copy the key straight away.** It's shown only once. One key does for both the add-on and Marso MCP. If you use two, make them both in the same Marso Studio account. See [API access](/marso-studio/api/api-access.md) for managing and revoking keys. ### 2. Install the Marso add-on 1. In [marso.app](https://marso.app/), open **Plugins** and download the **Blender** add-on. It comes as a single `.zip`. **Don't unzip it.** 2. Drag the `.zip` into the Blender window and accept the install. 3. Open **Edit → Preferences → System** and turn on **Online Access**. The add-on talks to Marso, and Blender blocks network access for add-ons until you do. ### 3. Set up the add-on and connect it Open **Edit → Preferences → Add-ons** and expand **Marso**: 1. **API Key**: paste the key from step 1. 2. **Cache Path** and **Downloads Path**: pick a folder for each. Downloads Path holds your imported assets, PBR maps and renders. 3. Under **Agent Connection**, tick **Connect to Marso Agents**. Leave **Agent Server** as it is. For every setting, see [Blender add-on](/marso-studio/plugins/m-xr-plugins/blender-add-on.md). ### 4. Add Marso MCP to your agent app Marso MCP is one URL: ``` https://mcp.api.marso.app/mcp ``` * **Claude Desktop:** open **Settings**, then **Connectors**, and choose **Add custom connector**. Name it Marso, paste the URL, and under **Authentication** choose **Sign in when needed**. * **Claude Code:** run `claude mcp add --transport http marso https://mcp.api.marso.app/mcp`, then run `/mcp` and pick **marso** to sign in. * **Codex:** run `codex mcp add marso --url https://mcp.api.marso.app/mcp`, then `codex mcp login marso`. The first time your agent uses Marso, it asks you to sign in to Marso MCP and paste your API key. Every step for each app is in [Connect your agent](/marso-studio/mcp/connect-your-agent.md). ### 5. Add Blender's MCP server Marso makes the model look real, lights it and renders it. To build the model, your agent uses Blender's own MCP server, from Blender Lab. 1. Install it from [blender.org/lab/mcp-server](https://www.blender.org/lab/mcp-server/), following the steps there: its add-on goes into Blender, and its MCP server goes into your agent app. 2. In Blender, start its server from that add-on's preferences. Blender's MCP server runs the code your agent writes, inside Blender. Save your work before you start, and read Blender's own advice on that page. ### 6. Check it's connected 1. In Blender's 3D Viewport, press **N** and click the **Marso** tab. The header shows **Agents connected as** your email. 2. In your agent app, start a new chat with Marso and Blender's MCP server switched on, and ask: "@marso Is my Blender connected?" Your agent checks the price with you before anything that spends credits. To let it carry on without asking, give it an allowance: "You can spend up to 200 credits without asking." ## Make something ### 1. Model it with your agent Describe a real object, and ask for each part as its own named object, with a colour close to its real material: > @marso Build me a 1910s brass desk fan in Blender: base, motor, six blades, wire guard, cord, each as a separate named part under one empty. Give every part a base colour close to the real material. > @marso Model a Victorian brass microscope from this photo, with bevelled edges, screws and knurled knobs. Make each part its own named object under one empty, and colour each part. Attach the photo to the second one. Your agent builds the parts in your scene and tells you when it's done. ### 2. Make it look real with Retexture > **Retexture runs from the Marso panel only.** Your agent can't start it through Marso MCP, so this step is yours. Asking your agent to retexture gets the reply that it stays in the Marso panel. In the **Marso** tab, open **Retexture**: 1. Click any part of the model, then **Use Whole Asset**. **What will be retextured** now names the model and how many parts it has. If the parts have no common parent, select them all and click **Group Selected into Asset** instead. 2. Describe the look: the materials, their age and wear, and where grime collects. For example, "galvanised steel, rust and flaking paint around the rim, wooden grip". 3. Leave **Prompt Enhance** as it is. It adds "lots of detail realistic lighting and shading" to the end of your prompt. 4. Check the cost, then click **Retexture**. Marso gives the whole model its new look, then adds predicted albedo, metallic, roughness, IOR and normal maps. Every part shares one texture and one material, and stays its own object. For the details, such as **Prepare UV** and a reference image, see [Retexture](/marso-studio/plugins/m-xr-plugins/blender-add-on.md#retexture). ### 3. Light it and render it Back in the chat: > @marso Set up a black studio, frame the object and render me a turntable. Your agent builds the studio, lights it, renders the turntable and shows it to you in the chat. The video also lands in `Renders/` in your Downloads Path. ### 4. Save your file Save the `.blend`. The materials live in it, and the maps are in your Downloads Path. ## Get the best results * **Describe a real object, or attach a photo of one.** Period, materials and wear matter more than adjectives. * **One object per material.** Brass, wood and enamel as separate parts give cleaner materials and a tidy outliner. * **Colour before you retexture.** Marso reads each part's current colour as a reference for your prompt. * **Ask for the small details:** bevels, rivets, seams and knurling. Lighting catches them, and that's what sells PBR. * **Opaque materials work best:** metal, wood, plastic, fabric and ceramic. * **Be specific in the Retexture prompt:** material, age, wear, where grime collects. ## More you can ask for * **Marso assets in your scene:** "@marso Make me a set of five kitchen props and put them in my Blender scene." Your agent makes them in Marso Studio and imports them. * **Assets from your Library:** "@marso Put the chair from my Lounge project into Blender." * **A showcase:** "@marso Arrange everything in the scene on a grid and render a showcase video." For everything your agent can do in Blender, see [Blender and Isaac Sim](/marso-studio/mcp/blender-and-isaac-sim.md). ## If something isn't working * **The Marso tab or a setting is missing:** see the troubleshooting table in [Blender add-on](/marso-studio/plugins/m-xr-plugins/blender-add-on.md#troubleshooting). * **Your agent says no Blender is connected, or sign-in fails:** see [Marso MCP troubleshooting](/marso-studio/mcp/marso-mcp-troubleshooting.md). * **Your agent can't build or change objects:** check Blender's MCP server is running in Blender and switched on in your chat. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.m-xr.com/marso-studio/plugins/m-xr-plugins/blender-with-your-ai-agent.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.