Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.
MCP in Unsloth Studio
Connect Blender MCP
Blender MCP is disabled by default. Unsloth Studio downloads a pinned, checksum-verified runtime on first enable/test and caches it on the backend machine. No commands, Git or pip installs are needed. Subsequent starts use the cache without internet. The Blender add-on is installed separately. No MCP archive or source is shipped in Unsloth Studio's Python package or desktop build.
- Open Manage MCP servers → Blender, approve the execution warning and choose Enable Blender MCP. Use a tool-capable model with MCP enabled for the chat.
- Open Setup help → Download Blender add-on for Blender's official page.
- In Blender 5.1+, enable Preferences → System → Network → Allow Online Access. Drag the website's install button into Blender twice: first to add the Blender Lab repository, then to install MCP. Alternatively, search MCP in Get Extensions after adding the repository.
- Enable and start the add-on bridge, keep Blender open, then Test connection.
A green dot means Blender is connected; amber means only the MCP server is connected.
Setup help stays in the same Blender entry. Advanced settings configure the bridge
port (default 9876) and optional Blender executable. This port is not an HTTP URL.
The bridge uses loopback on the Unsloth Studio backend machine, not a remote browser. Unsloth Studio does not install or launch Blender during setup. Approved tools can run Python, write files and launch background Blender. Existing tool permissions apply; external model providers receive tool results. Keep the unauthenticated bridge local.
The downloaded runtime excludes the large API/manual reference corpus and its three
offline documentation tools. The official source is
https://projects.blender.org/lab/blender_mcp (GPL-3.0-or-later).
The pinned revision and SHA-256 are in backend/integrations/blender/runtime.py.
Downloads are staged and verified before activation; failures leave the server
disabled and can be retried with Enable Blender MCP. Merely opening the dialog
or launching Unsloth Studio does not download anything.
Large tool catalogs
A server can expose dozens of tools with long descriptions and deeply nested parameter schemas: Notion's catalog alone is about 65,000 tokens. Every tool is listed in full while the catalog takes at most a tenth of the loaded local model's context window. External providers always get the full listing.
Past that, Unsloth searches tools the way Claude Code and Codex do. The model gets
mcp_tool_search, whose description names every tool with a one-line summary,
instead of the schemas. A search ranks the catalog with the SQLite FTS5 BM25 index
and rank fusion the knowledge base uses (tool names and descriptions searched
separately) and loads the best matches, exact names always; the model then calls
them with their full schemas. A tool the model calls by name loads the same way.
Up front, the listing also carries a tool a tool_choice forces, the tools mapped
to take an attached image, and, within a third of the window, the tools the chat
ran on earlier turns (so the prompt prefix the model server caches holds) and up
to five tools ranked against the user's message. Tools a turn loads stay within
half of the window, the oldest leaving first; a tool too large for that is refused
with a message naming it.
Unsloth Decisions MCP
When the Decision API is on (Settings → API), the chat's MCP menu lists
Unsloth Decisions. Enable it and a tool-capable chat model can call decide,
which asks the local Laya model the same typed questions POST /v1/systemone
answers (noul, choice and score), with the model chosen in Settings.
Other MCP clients reach the same tool at http://127.0.0.1:8888/mcp/decisions/
(use the actual Unsloth port). It takes the credentials /v1/systemone takes, so
send an Unsloth API key as Authorization: Bearer sk-unsloth-....
Unsloth Studio's own MCP server
Unsloth Studio has its own MCP server at /mcp/. Coding agents such as Claude Code and
Codex can use it to load models, chat, generate images, audio and video,
transcribe, train and export. Every tool goes through Unsloth Studio's own routes as
your API key, so it sees what that key may see and nothing more.
Turn it on
The server is off by default. While it is off, /mcp/ answers 404. The Unsloth
Studio owner turns it on in Settings > Agents with Allow agent connections.
Starting Unsloth Studio with UNSLOTH_STUDIO_ENABLE_MCP=1 also turns it on and
locks the switch, which then reads "Set by UNSLOTH_STUDIO_ENABLE_MCP."
The endpoint is http://127.0.0.1:8888/mcp/ on the default port. Always use
the trailing slash. Use your own address and port when they differ, for example
the LAN address or the Cloudflare tunnel URL.
Authentication
Every request needs an Unsloth Studio API key: Authorization: Bearer sk-unsloth-….
Create one in Settings → API. Unsloth Studio refuses everything else with 401:
- no key, an empty key, or a placeholder key such as
not-needed, even when keyless API access is on; - a signed-in session token;
- a revoked or expired key;
- the keys Unsloth Studio mints for its own recipe and Deep Research workflows.
A managed account's key works too. Its tools act for that account only.
Unsloth Studio does not offer OAuth. The OAuth discovery paths answer 404, so clients that probe them fall back to the key.
A browser page from another site gets 403 Origin not allowed for Unsloth Studio MCP.
This also blocks browser-based MCP inspectors. Command-line agents send no
Origin and are not affected.
Breaking changes
The static UNSLOTH_STUDIO_MCP_TOKEN is retired. A request that sends it gets
401 with this detail:
The MCP static token is no longer supported; use an Unsloth Studio API key (sk-unsloth-…)
If the variable is still set, Unsloth Studio logs one warning at startup. Unsloth Studio no longer refuses to start when the token is missing.
The tools changed:
| Old tool | New tool |
|---|---|
list_local_models |
list_models |
get_training_status |
studio_status |
stop_training |
cancel with kind="training" |
validate_recipe |
run_recipe with mode="validate" |
get_recipe_job_status, get_recipe_job_dataset |
get_job with kind="recipe" |
load_checkpoint and export_gguf |
export_model |
studio_status and start_training keep their names, but now run as your key.
Set up an agent
One command
unsloth mcp add writes the agent's MCP entry for you. It supports
claude-code, codex, cursor and generic:
unsloth mcp add claude-code
unsloth mcp add codex --url http://192.168.1.20:8888
unsloth mcp add cursor --dry-run
- The entry names the
UNSLOTH_API_KEYenvironment variable, never the key itself, and the command never prints a key. Pick another variable with--env-var. - It finds a running Unsloth Studio on this computer, or takes
--url. --dry-runprints the entry it would write and writes nothing. Running it again changes nothing.- A config file it creates is readable by you only (mode 0600).
codexalso setstool_timeout_sec = 300.genericprints a JSON entry to paste into any other agent's config.
Then check the connection:
unsloth doctor --mcp
It checks that Unsloth Studio answers, that your key works, and that the MCP
server is on. It also warns when an agent's tool timeout is under 240 s, because
long tools such as load_model can wait that long.
By hand
Each one reads the key from the UNSLOTH_API_KEY environment variable, so set
it before you start the agent. Replace http://127.0.0.1:8888 with your own
address.
Claude Code (macOS or Linux):
claude mcp add --transport http --scope user unsloth-studio http://127.0.0.1:8888/mcp/ --header 'Authorization: Bearer ${UNSLOTH_API_KEY}'
Claude Code (Windows PowerShell):
claude mcp add --transport http --scope user unsloth-studio http://127.0.0.1:8888/mcp/ --header 'Authorization: Bearer ${UNSLOTH_API_KEY}'
OpenAI Codex:
codex mcp add unsloth-studio --url http://127.0.0.1:8888/mcp/ --bearer-token-env-var UNSLOTH_API_KEY
Then set tool_timeout_sec = 300 under [mcp_servers.unsloth-studio] in
~/.codex/config.toml.
Long calls. A long chat reply, a song or a first model download can take
minutes, so raise your client's tool timeout above 240 s. For Codex that is
tool_timeout_sec = 300 above. For Claude Code, start it with
MCP_TOOL_TIMEOUT=300000 claude (the value is in milliseconds).
OpenCode, in ~/.config/opencode/opencode.json:
{
"mcp": {
"unsloth-studio": {
"type": "remote",
"url": "http://127.0.0.1:8888/mcp/",
"oauth": false,
"headers": {
"Authorization": "Bearer {env:UNSLOTH_API_KEY}"
}
}
}
}
Hermes Agent, in ~/.hermes/config.yaml, then run /reload-mcp in Hermes:
mcp_servers:
unsloth_studio:
url: "http://127.0.0.1:8888/mcp/"
headers:
Authorization: "Bearer ${UNSLOTH_API_KEY}"
OpenClaw, in ~/.openclaw/openclaw.json:
{
"mcp": {
"servers": {
"unsloth-studio": {
"url": "http://127.0.0.1:8888/mcp/",
"transport": "streamable-http",
"headers": {
"Authorization": "Bearer ${UNSLOTH_API_KEY}"
}
}
}
}
}
Mistral Vibe, in ~/.vibe/config.toml:
[[mcp_servers]]
name = "unsloth_studio"
transport = "streamable-http"
url = "http://127.0.0.1:8888/mcp/"
[mcp_servers.auth]
type = "static"
api_key_env = "UNSLOTH_API_KEY"
api_key_header = "Authorization"
api_key_format = "Bearer {token}"
DeepSeek Harness, appended to ~/.dsh/cordis.patch.yml:
- insert:
- id: mcp-unsloth-studio
name: '@deepseek-ai/dsh-mcp-client'
config:
serverName: unsloth-studio
transport: streamable-http
url: "http://127.0.0.1:8888/mcp/"
headers:
Authorization: !!js '`Bearer ${process.env.UNSLOTH_API_KEY}`'
Tools
| Tool | What it does |
|---|---|
studio_status |
What is loaded, loading and running: chat, image, video, speech-to-text and embedding models, training, export and GPUs. |
list_models |
Models Unsloth Studio can serve, by kind or by Audio page workflow. With model, its training defaults. With source="catalog", the image, video and audio models it can download, with their size and whether they fit on the GPU now. |
load_model |
Load a chat, image, video or speech-to-text model, downloading it first if needed. Reports progress, waits up to wait_s (240 s by default) and lists what it unloaded. |
unload_model |
Unload a model, or every chat, speech, image, video and speech-to-text model with kind="all". The embedding model stays. |
plan_load |
Preview a load without loading anything: GGUF variants and sizes, bytes to download, and the models it would unload. |
download_model |
Download a model ahead of time without loading it. Follow it with get_job; load_model waits for it. |
chat |
Ask the loaded model, with optional images, thinking controls and a response_format. Reports progress and returns a cancel_id. |
embed |
Embed up to 2048 texts, or rank them against a query and return the top_k best matches. |
system_one |
Ask the Decision API typed questions. The Decision API must be on. |
generate_image |
Text to image, image to image, inpaint, edit, reference, outpaint and upscale, one image or a batch of seeds or prompts. Left out, steps and guidance follow the loaded model. |
generate_audio |
Clone, speak, edit, convert, music and separate, on the loaded model or a named model. |
transcribe |
Speech to text, or translation to English; speakers labels who speaks, and expected_text adds a match score. |
analyze_audio |
A clip's duration, loudness, true peak, clipping and speech span, plus a match score against expected_text. |
generate_video |
Start a video, with a seed, frame count, last frame and image or audio references. One renders at a time. Poll it with get_job. |
get_job |
The state of a video, recipe, export, training or load job. With wait_s it waits for the job to finish or move on. |
list_media |
Earlier images, audio clips, videos, transcripts and saved voices, a page at a time. |
voices |
List, save, rename and delete saved voices. |
run_recipe |
Validate, preview or run a Data Recipe. |
datasets |
List, check, upload, download and follow training datasets, and upload image datasets for image LoRA training. |
start_training |
Start LLM, text-to-speech or image LoRA training. Follow it with get_job. |
list_training_runs |
Past runs and their checkpoints, by name. |
export_model |
Export a checkpoint to GGUF, merged weights, a LoRA adapter or the base model. |
cancel |
Stop running work of a given kind; the kinds are listed in the tool's schema. |
Long work keeps running in Unsloth Studio when a tool call times out.
Follow every long job with get_job(kind=…, id=…, wait_s=…): it checks every 2 s and returns once the job finishes, its status changes (for an export or a training run, also its phase), or wait_s runs out.
wait_s is at most 240; 50 stays under Codex's 60 s default tool timeout, and longer waits need a longer client timeout.
load_model waits up to wait_s too (240 s when unset), then returns status: "loading" and a job_id for get_job(kind="load").
Stop work with cancel.
Unsloth Studio runs one export at a time, so export_model is refused while another export runs, and cancelling an export job stops only that job's own step.
Choose tools
Every tool is on by default, including tools added by a later update. The
Unsloth Studio owner turns single tools off in Settings > Agents with Choose tools.
The choice covers the whole installation and every API key. A tool that is off
is left out of tools/list, and a call to it fails with
[tool_disabled] <tool> is turned off in Unsloth Studio. The owner can turn it on in Settings > Agents.
A prompt is hidden while a tool it reads (studio_status or list_models) is
off. The forced switch from UNSLOTH_STUDIO_ENABLE_MCP=1 does not lock the tool
choices.
Agents read the tool list when they connect, so an agent that is already connected keeps showing a tool you turned off until it reconnects. Its calls to that tool are refused at once.
Media and files
Generated images, audio and videos are saved to Unsloth Studio's galleries, the same as
in the UI. Tools return each item's id, its url and a download_url. The
download_url works without the API key for about an hour. It is bound to your
account and stops working when Unsloth Studio restarts, so call list_media for a
fresh one. The url needs the same Authorization: Bearer key.
return_media sets what else comes back. For images and video it defaults to
"inline": small images inline, large ones as a preview plus a link, and a video
as a thumbnail plus a link. "preview" sends a small image of preview_px pixels
(1024 by default), and "link" sends no media at all. Audio defaults to "link".
Pass "inline" to get a short clip itself. The MP4 is never sent inline.
list_media pages through earlier images, audio clips, videos, transcripts and
saved voices; pass its next_cursor back to get the next page. voices saves a
voice from a clip, so generate_audio can reuse it as reference={"voice_id": ...}.
A gallery video is an input too: {"video_id": ..., "frame": "last"} for an
image, or {"video_id": ..., "start_s": ..., "end_s": ...} for its sound.
Media inputs can be an Unsloth Studio id, inline data, or a file path. A file path
works only when the agent runs on the Unsloth Studio computer and connects over
loopback. From any other computer, send the data or an Unsloth Studio id instead.
An MCP request is limited to 4 MiB, so inline data has to fit in that. Send
larger media as an Unsloth Studio id, or as a path from the Unsloth Studio computer. A remote
agent can upload a large audio file, up to 200 MiB, to POST /v1/audio/inputs with its API key
and pass the returned id as input_id. The route takes the file's raw bytes as
the request body with a Content-Length, not a multipart form or JSON, and an
optional name query parameter:
curl -X POST "http://127.0.0.1:8888/v1/audio/inputs?name=meeting.mp3" \
-H "Authorization: Bearer $UNSLOTH_API_KEY" \
--data-binary @meeting.mp3
transcribe sends files up to 25 MB directly. Larger files, and audio given by
id, are uploaded to Unsloth Studio first, and their transcript is saved to Audio
history. Translation needs a file under 25 MB. Transcribing from a URL or a
YouTube link is not supported. timestamps needs a speech-to-text model that
times segments, such as Qwen3-ASR (audio.cpp) or Parakeet-TDT; other models
refuse it, and translation never has timestamps.
studio_status lists the loaded audio model's audio_options, such as its
built-in voices. Pass them to generate_audio in options. A voice or other
listed value is matched without regard to case, and a value the model does not
list is refused.
Tool results never contain paths on the Unsloth Studio computer. Checkpoints are named
<run folder> or <run folder>/checkpoint-N. Exports are named relative to
Unsloth Studio's exports folder, and export_model takes only a relative
save_directory.
Prompts
The server also offers two prompts, which Claude Code shows as slash commands:
make_short_film and build_dataset_and_train. Each one reads what is loaded
and which catalog models fit on the GPU right now, then lays out the tool calls
for the job.
Known limits
- An API key cannot unload a chat model that was loaded from a local folder. Unsloth Studio shows such a model to API keys under an opaque reference, and the unload route does not resolve it. Unload it in the Unsloth Studio UI.
- Unsloth Studio runs one Data Recipe job at a time, and a recipe job id is not tied to an account. Anyone with a key who knows the id can read that job's status.
- Models can be unloaded between calls when an idle timeout is set. Tools then say to load the model again.