@sharpiiai/mcp

The official MCP server for Sharpii.ai. Lets Claude / Claude Code / Cursor / Windsurf generate images, videos, audio, upscale, and edit media via natural language.

npx -y @sharpiiai/mcp --api-key=shp_your_key

Install in your host

Claude Desktop / Claude Code / Cursor / Windsurf

Add to your host's MCP config:

{
  "mcpServers": {
    "sharpii": {
      "command": "npx",
      "args": ["-y", "@sharpiiai/mcp"],
      "env": { "SHARPII_API_KEY": "shp_..." }
    }
  }
}

Get an API key at sharpii.ai/account/api-keys.

What it does

20 tools across 6 areas:

| Area | Tools | |---|---| | Settings & diagnostics | set_api_key, debug_credentials, list_models | | Credits & usage | get_credit_balance, get_usage | | Tasks | get_task, wait_for_task, upload_file, download_output | | Image | generate_image, generate_image_and_wait, upscale_image, edit_skin | | Video | generate_video, edit_video, animate_image, lipsync | | Audio | generate_speech, generate_music, clone_voice |

Plus 5 read-only resources (sharpii://models, sharpii://aspect-ratios, sharpii://presets/skin-modes, sharpii://presets/voices, sharpii://docs/quickstart) and 24 expert prompts — 4 direct workflows (cinematic_portrait, product_shot, animate_my_photo, make_a_short) and 20 planning skills that ask clarifying questions first and chain real Sharpii model IDs (kling-3.0-pro-t2v multi-shot, veo3.1-fast first-frame, ideogram-v3 for text rendering, nano-banana-pro with reference images, vocolab voice presets, avatar lipsync, etc.) — never generic.

| Skill | What it does | |---|---| | vibe_picker | Surfaces 8 vibes and routes to the matching skill | | scene_customizer | Asks what to change in a supplied photo before feeding to a model | | scene_planner | Storyboards multi-shot sequences (kling-3.0 / sora-2 / veo3.1-fast) | | videographer | Lens / move / framing / lighting / palette → ready-to-paste prompt | | viral_hook_writer | 5 hook scripts (curiosity / shock / contrarian / relatable / promise) | | ugc_maker | Persona + hook + scene + voice + lipsync, end-to-end | | social_hook | 3-second visual scroll-stopper (single shot or 3-shot loop) | | explainer_video | SaaS / educational, sora-2 storyboard or kling-3.0 multi-shot | | product_360 | Turntable video OR multi-angle static set with references | | brand_story | 4-beat emotional arc, character continuity via kling-3.0-pro-i2v | | music_video_concept | Beat plan + suno-v5 audio bed | | cinematic_style | 5 cinematographer-tagged prompts (Deakins / Lubezki / Anderson / Doyle / Young) | | anime_action | Subgenre + studio refs + sakuga keywords | | cgi_3d_style | Pixar / Unreal / Octane prompt patterns | | fight_scene | Choreographed beats with kling-3.0 multi-shot | | motion_design_ad | 6-12s SaaS launch with ideogram-v3 typography frames | | ecommerce_ad | Platform-optimized (TikTok Shop / Meta / Amazon / Shopify) | | fashion_lookbook | Multi-look continuity via reference_images + kling-3.0-pro-i2v | | real_estate_tour | Continuous walkthrough or per-room beats | | food_beverage_ad | ASMR macro / recipe multi-beat |

Output mode — where generated media goes

By default every result is auto-saved to a local folder, in addition to the CDN URL:

• macOS / Linux: ~/Documents/Sharpii/
• Windows: %USERPROFILE%\Documents\Sharpii\

Override the folder with SHARPII_MCP_OUTPUT_DIR=/absolute/path. To skip the local copy entirely (URLs only), set SHARPII_MCP_OUTPUT_MODE=urls.

| Var | Default | Effect | |---|---|---| | SHARPII_MCP_OUTPUT_MODE | files | files (default) auto-downloads to disk + returns URL + local path. urls returns CDN URLs only. | | SHARPII_MCP_OUTPUT_DIR | ~/Documents/Sharpii/ | Directory for saved files. | | SHARPII_MCP_FILENAME_TEMPLATE | {model}-{task_id_short}-{index}.{ext} | Filename template tokens. |

Changing the API key

Three priorities (highest first):

1. --api-key=shp_... CLI flag.
2. SHARPII_API_KEY env var.
3. The set_api_key tool — persists to ~/.sharpii/mcp.json. Use this to swap keys without editing host config JSON.

Local files

Every media argument accepts a URL, a local path, or a base64 data URI. Local paths are uploaded to Sharpii's CDN automatically before the API call:

Upscale ./photo.jpg to 8K with the smart upscaler.

The MCP reads the file from your project directory, uploads it, and submits the upscale job — no manual upload step needed.

Errors

Every tool error has a structured _meta.sharpii.error_code, e.g.:

| Code | Meaning | |---|---| | no_api_key | Set SHARPII_API_KEY or use set_api_key. | | credits_too_low | Top up at sharpii.ai/billing. | | unknown_model | Call list_models. | | content_policy_violation | Re-prompt; no charge. |

Run debug_credentials first when something's not working.

Documentation

• Full setup walkthrough: sharpii.ai/api-documentation/mcp
• API reference: sharpii.ai/api-documentation

License

MIT.