Nano Studio Pro

npx add-mcp 'https://nanostudiopro.com/api/mcp'

MCP server for your image library

Give Claude Desktop, Claude Code, or any host that speaks the Model Context Protocol one searchable home for your media. Upload or import any photo — yours or generated elsewhere — and your agent can find it again by the objects, colors, and scenes inside it, instead of hunting through folders. 31 tools — search, detections, assets, projects, entities, generation, editing, cutouts, video, storyboards, tasks — all backed by the same /v1 API documented at /docs.

Install

The quickest path is through the CLI — nsp mcp downloads and runs the MCP server on first use, so this is the whole setup:

curl -fsSL https://nanostudiopro.com/cli/nsp -o /usr/local/bin/nsp && chmod +x /usr/local/bin/nsp
claude mcp add --scope user nanostudio nsp mcpbash

Without the CLI, the server also runs as a single file. That copy is frozen at download time:

curl -fsSL https://nanostudiopro.com/cli/mcp -o /usr/local/bin/nsp-mcp \
  && sudo chmod +x /usr/local/bin/nsp-mcpbash

Pure Node.js, zero dependencies, single file. Requires Node 18+. Inspect the source at https://nanostudiopro.com/cli/mcp before installing if you like. Through the CLI the cached copy refreshes itself: every launch asks the server for its version and re-downloads when a newer one is out, so new tools arrive on the next reconnect (offline, the cache runs as is). Force it with nsp mcp --update. The standalone binary does not self-update; re-run the curl, or connect to the remote URL instead.

Sign in

nsp login   # optional — skip it and the first tool call signs you in from chatbash

The MCP server reads the same ~/.config/nsp/credentials.json the CLI writes — so one nsp login covers both. For headless use, set NANO_API_TOKEN:

NANO_API_TOKEN=sk_sf_live_... nsp mcpbash

Not signed in at all? Also fine — the first tool call starts a browser sign-in (RFC 8628 device flow) and hands the approval link to the agent. Approve it in the browser, tell the agent to retry, and the token is saved for next time.

Wire it up

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) and add:

{
  "mcpServers": {
    "nanostudio": {
      "command": "nsp",
      "args": ["mcp"]
    }
  }
}json

Quit Claude Desktop fully and reopen. The nanostudio server appears in the MCP panel.

Claude Code

claude mcp add --scope user nanostudio nsp mcpbash

--scope user makes the server available in every project. Use --scope project to scope it to a single repo (writes a .mcp.json).

Remote server — no install

The same tools are also hosted at https://nanostudiopro.com/api/mcp. Any MCP host that connects to a URL and can send an Authorization header works — nothing to download. In Claude Code:

claude mcp add --transport http --scope user nanostudio https://nanostudiopro.com/api/mcp \
  --header "Authorization: Bearer sk_sf_live_..."bash

Create the token in Settings · API Tokens or print an existing one with nsp token. The hosted server exposes the same tools minus the local-filesystem parameters (path, save_to), and project_id is always required.

OAuth hosts need no token at all: in a claude.ai or Claude Desktop custom connector, just paste https://nanostudiopro.com/api/mcp as the server URL — the host discovers the OAuth endpoints automatically, a browser window opens, and you approve the connection (choosing permissions and an optional daily credit cap) exactly like authorizing a device. Revoke it any time from Settings · Connected Apps.

Add to Cursor one-click install of the remote server in Cursor.

Tools

Find

Every image — generated here or uploaded from anywhere — is scanned on the way in, so the agent can look things up by the objects, colors, and textures inside them rather than guessing at filenames.

Tool	Wraps	Cost	What it does
search	GET /v1/search	free	Detection-aware search across assets and generations — scope by project, filter by type/style/aspect/colors, browse newest, match a color, or find images similar to one you have; include_regions adds bounding boxes. Reaches inside indexed videos too: a matching hit can be the exact second of a clip (video_moment), and gen_type narrows to one kind (video, cutout, …).
get_detections	GET /v1/detections/{id}	free	What the detection engine sees: items, colors, textures, bounding boxes, scene narrative.
list_generations	GET /v1/generations	free	Generations in a project; favorites:true = only the hearted ones, the shots the user marked as best.
list_assets	GET /v1/assets	free	Uploads and reference images.
get_asset	GET /v1/assets/{id}	free	Fetch asset metadata.
sounds	/v1/sounds, /v1/sounds/{id}, /v1/sounds/upload	free; make per second of sound (per character for a voice line), purchased credits only; upload counts toward storage	The sound library: every music track, effect, ambience and voice made or added anywhere in the app, each with a signed file url. Actions search (newest first or best match for q: name, words, tags; narrow by kind, category, language or project; hidden ones only when asked), get, edit (rename, recategorise, retag, set the language, hide; there is no delete), make (music, an effect, an ambience or a voice line read verbatim; quote it with dry_run, which lists the voices), upload (a link; the local server also takes a file path) and record. Through the local server, record takes the Mac's microphone with ffmpeg for up to 300 seconds and files the take as a voice recording, named from what is said a few seconds later; through the remote server it answers a link that opens the recorder on the Sounds page.

Add to the library

Not just images made here. Any local file or URL can come in, and the scan that makes it searchable runs on the way through.

Tool	Wraps	Cost	What it does
add_image	POST /v1/assets, /v1/generations/upload	3 cr + storage	Bring in any local file or URL: as a reusable reference (default), into a project timeline, or as a product photo. The 3 credits are the scan that makes it searchable. The reply names other versions of the picture already in the library (larger, smaller, same size).
add_video	POST /v1/videos/uploads, /v1/videos/import	storage	Bring in a video of any size your space allows: a local file goes straight to storage in parts, a direct link is imported in the background (poll get_task). density also indexes it for search, priced like indexing. metadata carries your own fields, a file already in the project is not stored twice, and other versions of it already in the library are named in the reply. Every clip gets a light 1080p editing copy (counted in storage); keep_original: false drops the uploaded original once the copy exists, leaving that clip at 1080p.
scan_image	POST /v1/scans	3 cr	Run the detection scan on an image that was never scanned.
delete_asset	DELETE /v1/assets/{id}	free (destructive)	Permanently delete. Description warns the model to confirm with the user.

Organize

One project per folder, resolved by name — so a repo's imagery stays separate and searchable on its own. This is also where the recurring cast lives: the people, props and places an agent reuses from shot to shot.

Tool	Wraps	Cost	What it does
resolve_project	GET+POST /v1/projects	free	Find a project by name or create it — idempotent; or fetch one by project_id. Backs the one-project-per-folder convention.
list_projects	GET /v1/projects	free	Projects, newest first.
list_entities	GET /v1/entities	free	People, props, places, skins and a character's looks that recur, each with its reference set; with id, one entity in full: its baked sheet (prefer sheet.asset_id as the reference), items sheet, looks, links, bio, voice.
save_entity	POST/PATCH /v1/entities, /v1/entities/{id}/links	free	Create (find-or-create by kind and name) or edit a character, prop, place, skin or look: its reference set (replaced), a description and other traits (merged), and links to others (wears, carries, rides, lives in...) added or removed in the same call.

Create and edit

The generation surface, filing straight into the library above.

Tool	Wraps	Cost	What it does
generate_image	POST /v1/generations	credits	Generate on Nano Banana 2 or Pro, or GPT Image 2.5 Flare / Sunburst (`model`). Returns the image inline so the model can see it.
sheet_options	GET /v1/sheets/options	free	The menus a sheet is made from: kinds, grounds, styles, animation sequences by subject or game with frame counts per level, models. `family` + `type` drills into one type's frame lists.
generate_sheet	POST /v1/sheets	credits	One image of several separate elements laid out to be cut out — an animation cycle, a sprite sheet, an icon set, stickers, props — planned, prompted and recorded server-side from ids. `dry_run` quotes; `prompt_only` returns the plan and exact prompt, free, for generating elsewhere.
get_sheet_atlas	GET /v1/sheets/{id}/atlas	free	A sheet's frame rects, registration, fps, pivot and one tag per sequence, as Aseprite JSON for Phaser, Pixi, Godot, Unity.
restyle	POST /v1/restyle	credits	AI-edit an image: one-click product placement, item recolor/remove/add, merge, style transfer, plain-text edits.
cutout	POST /v1/cutouts	credits	Subject cutout: transparent PNG, matte, and clean background plate.
get_cutout	GET /v1/cutouts/{id}	free	Fresh signed URLs for an existing cutout.
expand_image	POST /v1/expand	credits	Outpaint to a bigger canvas / new aspect ratio.
upscale_image	POST /v1/upscale	credits	Re-render at a higher resolution.
storyboard	/v1/storyboards	free; make_keyframes 1 image per keyframe; write_dialogue 1 scan per picture; check_continuity per frame read and per comparison call; isolate_voices per second of audio; write_score_plan and assist per call; score per second of music; suggest_effects 1 scan per take; make_effects per second of sound; make_voice_over, make_director_commentary and read_lines per character; make_stills 1 image per still; make_song per 10 s of music; make_beds per 10 s of sound; clean_score_endings free	Plan a short film the owner watches being built on its page: keyframes (frozen images), segments (camera work and action between two keyframes), dialogue timed to the second, decisions that branch it. An agent may write the whole film itself, free: every operation is plain text, a keyframe's or still's picture can be any image the owner has (an assetId from add_image), a clip any video they have (use_clip), and the AI actions are optional. Actions list, get (every path with its timeline and how each moment arrives as the player will play it: cut, dissolve or fade through black, its length and why; readiness; the title and end screens; the film's posters, newest first, and which is in use; format=script reads the film as Markdown), create, change (the page's own operations, which edit and remove as well as add, including trims and speed ramps, transitions and carried sound, the film's sound list, each place's looped sound, the title and end screens' pictures, words and music, setPoster to pick among the film's posters (a new one joins them) and removePoster to take one out), undo, redo, events, make_keyframes (each keyframe's picture made in the film's look, with its style references, cast, outfits and place, and set on it; quote it with dry_run), write_dialogue, check_continuity (the AI reads the film's clips and pictures and points at what does not match from one shot to the next, each finding with its frames in readiness; quote it with dry_run; setAiFeedback marks a finding intended, wrong or correct with a note the next check reads), isolate_voices (Voices only: each take's voices kept apart from its clip's music and effects, so the film's music and ambience dip under speech only; quote it with dry_run; setMix sets each sound layer's level and setVoicesOnly switches a take back to its full sound), score (Score this film: music composed for the cut, one section per stretch of story timed to the timeline, each path from where it splits, placed as music cues; quote it with dry_run, which shows each composition plan; addMusicCue, updateMusicCue and removeMusicCue place, move, level and take off music by hand; setScoreDirection says how the whole score should sound, and setScoreSection and clearScoreSection edit one section's styles or put it back to automatic), write_score_plan (the AI writes how each section of the score should sound, and why, from the film and the direction, onto the storyboard, keeping sections edited by hand; quote it with dry_run; score then composes exactly that plan), assist (the guided steps' AI buttons, by kind: place suggests a place for the film, plot proposes a plot, improve improves the story keeping its events, keyframes drafts the first moments and any decisions of a film with at most one moment; each answers a proposal and the ops that keep it, nothing is saved by itself; quote it with dry_run), suggest_effects (the AI reads each take's frames and proposes small sounds timed to what is on screen, steps, a door, a coat; quote it with dry_run; nothing is placed), make_effects (makes the ones you keep with ElevenLabs, at one loudness, and places each on its take; quote it with dry_run; addEffect, updateEffect and removeEffect place, move, level, pitch and take off effects by hand), make_voice_over (reads the film's narration with ElevenLabs in each line's voice, a curated set with a storyteller first, and links each line to its sound; quote it with dry_run, which lists the voices; addVoiceOverLine, updateVoiceOverLine, removeVoiceOverLine and setNarrator place a line on a moment, rewrite it, change its voice and take it off), make_director_commentary (reads the typed lines of the director's commentary in the director's voice; commentary is pieces at a film second on tracks, each track on the path it was made on, heard on /watch when the viewer turns it on; quote it with dry_run; addDirectorSegment, updateDirectorSegment, removeDirectorSegment and setDirectorVoice place, move, rewrite and take off commentary; recording with a microphone is the page's alone), make_stills (the animatic's photographs, each made in the film's look at a point of a segment; quote it with dry_run), read_lines (the dialogue read aloud in each speaker's voice; quote it with dry_run), make_song (a song sung in the film from its styles and verses, placed as a music cue; quote it with dry_run), make_beds (each place's looped sound from its words; quote it with dry_run), clean_score_endings (free: cuts the noise the music model sometimes leaves after a cue ends), use_clip (free: a video the owner already has, imported with add_video or made earlier, becomes a segment's, loop's or ending shot's clip, its length set to the clip's), generate (the video clips, per second; quote it with dry_run), trim, share (a public /watch link that plays a frozen copy; sharing again updates the same link; dry_run reads how it is watched: views, viewers, endings reached, the split at each decision), delete. Every change is signed as the agent in the storyboard's log.
generate_video	POST /v1/videos	per second	Make a video from an image: Kling 3.0 / Omni / O1 / Motion Control, Veo 3.1 Lite, Gemini Omni Flash or Seedance 2.5, with end frames, reference clips and stills. The priciest operation; quote it with dry_run first, deducted on completion.

Account and tasks

Feature detection, budgeting, and the background-job surface.

Tool	Wraps	Cost	What it does
whoami	GET /v1/me, /account/credits, /storage, /meta	free	User, plan, credits and daily cap, storage and quota, and the server's version and capabilities, in one call.
get_pricing	GET /v1/pricing	free	Credit cost of every operation.
list_tasks	GET /v1/tasks	free	Background tasks (generations, scans, exports).
get_task	GET /v1/tasks/{id}	free	Status of a single task; a video task also returns its signed video + preview URLs when done.
cancel_task	POST /v1/tasks/{id}/cancel	free	Stop a running task. Description warns to confirm.
retry_task	POST /v1/tasks/{id}/retry	free	Retry a failed task.

Image generation over MCP

The biggest reason to use the MCP server over the CLI is that generate_image returns the rendered PNG as an inline MCP image content block. Your LLM literally sees what it generated and can critique, refine, or call the tool again with adjustments — without the user having to copy a file path back into chat.

If you also want the file on disk, pass save_to: "./gen.png" — the file is written and the image still streams back to the model.

Costs are surfaced in the tool description so the model can budget. After every call the response includes credits_remaining so the model knows when to back off.

Sprite sheets and game assets over MCP

Ask any image model for “eight frames of a knight running” and you get a picture, not a sheet: frames at different sizes, touching each other, on a ground that will not key, and no file saying where frame three starts. Three tools take that whole job off the agent.

• sheet_options returns the menus as data — kinds (icon set, sticker sheet, pixel sprites, animation, props), keyable grounds, styles, animation sequences by subject or by game genre with the frame count at each level of detail, and the models. Free.
• generate_sheet takes those ids rather than prose. The grid, the gutters, the flat ground and the asserted frame count are decided server-side, so the agent cannot trim the one thing the prompt exists to protect: the count. dry_run quotes the credits before anything is spent.
• get_sheet_atlas hands back every frame's pixel rectangle, the registration, the speed, the pivot and one animation tag per sequence, as the Aseprite-format JSON that Phaser, Pixi, Godot and Unity already import. Free.

The same three run the Sheets section of the app and the /v1/sheets endpoints; the announcement post walks through what a sheet is and how one is planned.

AI image editing over MCP

restyle edits an image you already have instead of generating a new one: recolor, remove or add a single item, place a product into a scene, merge two pictures, carry one image's style onto another, or just describe the change in plain words. The image can be a generation or a photo you uploaded (asset_id); an upload is only read, and the edit is always saved as a new image.

Targeting an item by name works because the picture was scanned on the way in. Call get_detections first — it is free, and it returns the exact item names, colors and boxes the engine saw, which are the names restyle expects. Guessing at “the jacket” when the scan recorded “navy bomber” is the usual reason an edit misses.

expand_image outpaints to a wider canvas or a new aspect ratio, and upscale_image re-renders at a higher resolution. Both cost credits and both file the result back into the same project, so the edit stays searchable next to its original.

Cutouts and background removal over MCP

cutout separates the subject from its background and returns three things, not one: the transparent PNG, the matte, and a clean plate of the background with the subject removed. The plate is what makes it useful for composition — you can put the subject somewhere else and still have the room it came out of.

Signed URLs expire; get_cutout hands back fresh ones for a cutout that already exists, free, so an agent never has to pay twice for the same subject. It works on any image in the library, including ones you imported.

Video generation over MCP

generate_video turns a still into a clip, with the model named in the call: Kling 3.0, Kling 3.0 Omni (reference clips and stills, up to 4K), Kling O1, Kling Motion Control (copy a real performance onto your still), Veo 3.1 Lite with sound, Gemini Omni Flash, which also edits a finished clip from a description, or Seedance 2.5, for takes up to 30 seconds with dialogue in sync. End frames are supported where the model has them.

It is the most expensive operation on the server — priced per second, hundreds to thousands of credits a clip — so it is built to be quoted before it is run: dry_run returns the price and nothing is deducted until the render completes. get_task polls the job and returns signed video and preview URLs when it is done.

Finished clips are indexed like pictures: search reaches inside them and a hit can be the exact second of a clip rather than the whole file. See image and video search for agents.

Characters, mounts and items over MCP

The characters, props, places and outfits you build in the app travel with you. An agent reads them and uses them in a generation, and can make and edit them too with save_entity: name, reference pictures, a description, and links such as wears, rides or lives in. Free.

• list_entities lists them, narrowed by kind: character, prop, place, look or skin (an outfit with its accessories). Free.
• With an id it returns one in full: its views and baked reference sheet, its looks, its bio and world, its voice, and its links: what it wears, what it carries, and what it rides. A mount is a prop linked by rides, so one call gives a character's mounts and accessories together.

In a prompt, an @-mention works exactly as it does in the app's Prompter, in generate_image, restyle,generate_video and generate_sheet:

• @nano attaches the character's reference sheet.
• -@nano leaves it out.
• @nano/alone brings the character without its items.

An agent can pass entity_ids instead of writing mentions, and every response says what each mention attached and what it left out.

MCP, API or CLI

Three doors to the same account, credits, library and characters. The MCP tools are a thin layer over the public /v1 API, so prices, limits and results are the same whichever one you use.

Door	Best for	Signs in with
Hosted MCP (remote server)	An agent in Claude, Cursor or ChatGPT	One approval in the browser; the app keeps the sign-in
nsp mcp (local)	The same 31 tools, plus reading and writing files on your disk	nsp login, once per computer
REST API	Scripts, bulk work and build pipelines	A personal token from Settings → API Tokens
CLI commands	Quick checks and a one-line image from the terminal	nsp login

The CLI's own commands are a small set (account, credits, projects, generate an image); everything else is in nsp mcp. The hosted and local servers offer the same tools with the same options, and a test keeps them that way. An agent cannot read its MCP sign-in, so for a script it needs a personal token from you.

Default project

generate_image, cutout, and add_image into a timeline resolve project_id when the model omits it: first from the nearest .nsp.json (walking up from the working directory), then from default_project_id in your credentials file. Set the global fallback with nsp use <id>.

To pin a repo to its own project, drop {"default_project_id":"prj_..."} in a .nsp.json at its root — or skip the file entirely and let the agent call resolve_project with the folder name to find-or-create one. One project per folder keeps every repo's imagery separate and searchable on its own.

Import your own images over MCP

The tools are not only for images generated here. add_image accepts any local file or URL — drop in existing product shots, artwork, or brand imagery. Every import runs through the same detection scan that powers search: detected objects, colors, and textures become instantly searchable, and any imported image can be cut out, used as a generation reference, or organized into projects like everything else.

Importing your existing images covers which tool to use for what, where imports land, and what the scan costs.

Prefer the terminal? The CLI has the same operations. Need the raw HTTP surface? The full API reference is one click away.