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. 35 tools — search, detections, assets, projects, generation, editing, cutouts, video, 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.
list_assets	GET /v1/assets	free	Uploads and reference images.
list_favorites	GET /v1/generations?favorite	free	Favorited (hearted) photos in a project, newest first — the shots the user marked as best.
get_asset	GET /v1/assets/{id}	free	Fetch asset metadata.

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
upload_asset	POST /v1/assets	3 cr + storage	Upload from local path or remote URL. The scan that makes it searchable is the 3 credits.
import_image	POST /v1/generations/upload	3 cr + storage	Import a local or remote image into a project timeline (no generation). The 3 credits are the scan that makes it searchable.
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.

Tool	Wraps	Cost	What it does
resolve_project	GET+POST /v1/projects	free	Find a project by name or create it — idempotent. Backs the one-project-per-folder convention.
list_projects	GET /v1/projects	free	Projects, newest first.
create_project	POST /v1/projects	free	Create a new project.
get_project	GET /v1/projects/{id}	free	Fetch one project.

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.
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.
plan_sheet	POST /v1/sheets/plan	free	The prompt-only door: the plan and the exact prompt, for generating elsewhere. Prefer generate_sheet.
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.
generate_video	POST /v1/videos	per second	Make a video from an image: Kling 3.0 / Omni / O1 / Motion Control, Veo 3.1 Lite or Gemini Omni Flash, with end frames, reference clips and stills. The priciest operation; quote it with dry_run first, deducted on completion.
get_video	GET /v1/videos/{task_id}	free	Poll a video job; returns signed video + preview URLs when done.

Account and tasks

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

Tool	Wraps	Cost	What it does
whoami	GET /v1/me	free	Authenticated user, plan, credit balance.
get_meta	GET /v1/meta	free	Server version + capability flags for feature detection.
get_credits	GET /v1/account/credits	free	Wallet balance + token daily-cap status.
get_pricing	GET /v1/pricing	free	Credit cost of every operation.
get_storage	GET /v1/storage	free	Storage usage and quota.
list_tasks	GET /v1/tasks	free	Background tasks (generations, scans, exports).
get_task	GET /v1/tasks/{id}	free	Status of a single task.
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.

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, or Gemini Omni Flash, which also edits a finished clip from a description. 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_video 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.

Default project

generate_image, cutout, and import_image 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. import_image and upload_asset accept 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.