Repository avatar
Other Tools
v1.2.1
active

avatarsay-mcp

io.github.fourgit/avatarsay-mcp

Roll RPG NPCs (Foundry VTT & SillyTavern V2), import stylized art, MP3 barks & talking MP4s.

Documentation

AvatarSay MCP Server (v1.2.0)

npm version CI AvatarSay MCP Server MCP server – quality and maintenance score on Glama License: MIT

Roll complete tabletop RPG / D&D NPCs (SillyTavern Character Card V2 + Foundry VTT Actor JSON), import your existing non-photorealistic character illustrations & VTT tokens, synthesize fast (<3s) tabletop MP3 voice barks, generate original fictional character portraits (2 × 1024 px in 8 styles: Anime, 3D Cartoon, Pixel Art, Fantasy, Cyberpunk, Watercolor, Realistic, Professional), and animate them into lip-synced square talking videos (960×960 H.264 MP4, 8 built-in English voices, zero watermark) directly from Claude Desktop, Claude Code, Cursor, Windsurf, or any Model Context Protocol (MCP) client.

  • Remote MCP Endpoint (recommended, zero install): https://avatarsay.com/mcp
  • Setup Guide & Live Docs: https://avatarsay.com/mcp
  • API Keys: https://avatarsay.com/dashboard#mcp
  • Free Trial & Pay-Once Pricing:
    • Public zero-key NPC roller: roll_rpg_npc and list_voices_and_styles run at 0 credits with no API key required.
    • 30 free signup credits + 1 free talking MP4 via MCP: New accounts receive 30 free credits (up to 7 portrait pairs = 14 avatars, or 15 instant .mp3 NPC voice barks at 2 credits each) plus 1 free <=5s (<=75-char) talking MP4 clip (0 credits via MCP or web, zero watermark).
    • No subscription: One-time credit packs start at $9.90 for 500 credits and never expire (pricing details).

Quick Start (Zero-Install Remote HTTP)

Modern MCP clients connect directly to https://avatarsay.com/mcp via Streamable HTTP — no local runtime needed.

Cursor / Windsurf (.cursor/mcp.json)

{
  "mcpServers": {
    "avatarsay": {
      "url": "https://avatarsay.com/mcp",
      "headers": {
        "Authorization": "Bearer avs_YOUR_API_KEY"
      }
    }
  }
}

Claude Code (CLI)

claude mcp add --transport http avatarsay https://avatarsay.com/mcp \
  --header "Authorization: Bearer avs_YOUR_API_KEY"

Claude Desktop (stdio Bridge — Official npm Package)

Add avatarsay-mcp to claude_desktop_config.json:

{
  "mcpServers": {
    "avatarsay": {
      "command": "npx",
      "args": [
        "-y",
        "avatarsay-mcp"
      ],
      "env": {
        "AVATARSAY_API_KEY": "avs_YOUR_API_KEY"
      }
    }
  }
}

(You can omit AVATARSAY_API_KEY if you only want public discovery and roll_rpg_npc.)


Tabletop VTT & Roleplay Companion Plugins

Using Foundry VTT or SillyTavern directly at your table? Install the official open-source companion plugins alongside MCP:

  • Foundry VTT Module (v12 / v13): fourgit/avatarsay-foundry-vtt
    1-line install in Foundry VTT → Add-on Modules → Install Module → Manifest URL:
    https://github.com/fourgit/avatarsay-foundry-vtt/releases/latest/download/module.json
  • SillyTavern Extension: fourgit/avatarsay-sillytavern
    1-line install in SillyTavern → Extensions → Install extension → Git URL:
    https://github.com/fourgit/avatarsay-sillytavern

Available MCP Tools (10 Tools)

ToolAuthCredit CostDescription
list_voices_and_stylesPublic (none)0Lists all 8 art styles, 8 English voices (with .mp3 sample URLs), VTT/SillyTavern plugins, free-clip rules, voice-bark pricing, and one-time credit packs.
roll_rpg_npcPublic (none)0Deterministic tabletop RPG / D&D NPC generator with optional seed, style, gender, ancestry, role, and exportFormat filters. Returns full NPC sheet, <=75-char greeting (fits free 5s video!), SillyTavern Card V2 JSON, Foundry VTT Actor JSON, and copy-pasteable nextToolCalls.
get_creditsBearer avs_…0Checks current credit balance, quality tier (standard vs hd), firstFreeVideoAvailable & firstFreeVideoStatus, and remaining capacity across avatars, MP3 voice barks, and video seconds.
list_avatarsBearer avs_…0Lists recent generated and imported character portraits (ast_…) with 24-hour signed URLs.
list_videosBearer avs_…0Lists recent 960×960 lip-synced talking MP4 videos (ast_…) with 24-hour signed download URLs.
generate_avatarsBearer avs_…4 (Std) / 6 (HD)Enqueues 2 × 1024 px character portraits from a text prompt and returns jobId immediately (~5–10s render).
import_character_portraitBearer avs_…0Imports an existing non-photorealistic fictional character illustration (PNG / JPEG / WebP, 256–4096 px, <=5 MB, confirmFictional: true) via imageUrl or imageBase64 so you can animate VTT tokens or Midjourney art with create_talking_video. Real human photos and camera EXIF are blocked.
create_npc_voice_lineBearer avs_…2 / 100 chars (min 2)Synchronous (<3s) tabletop NPC .mp3 audio bark (1–500 chars, optional speed 0.8–1.2 and emotion). Stores MP3 and returns a 24-hour signed download URL immediately (auto-refunds on error).
create_talking_videoBearer avs_…0 (1st <=5s clip), then 12 / sec (min 60)Enqueues a watermark-free lip-synced 960×960 MP4 (5–30s) from any generated or imported ast_… portrait and returns jobId immediately without blocking. First <=5s (<=75-char) clip is 0 credits on eligible unpaid accounts!
get_jobBearer avs_…0Polls queued / running / succeeded / failed status for image or video jobs and returns 24-hour signed download URLs (auto-refunds failed renders).

Built-In MCP Prompts (3 Workflow Templates)

  • create-rpg-npc — Roll an NPC with SillyTavern V2 + Foundry VTT exports, generate 2 portraits, and render an instant MP3 voice bark or free 5s talking MP4.
  • prep-tavern-encounter — Prep a 3-NPC tavern/dungeon encounter with interconnected hooks, VTT JSON imports, and tabletop MP3 greetings.
  • create-talking-intro — Design a fictional mascot or channel character and animate a short spoken intro clip.

Trust & Safety

  • Fictional & stylized characters only: Generates original characters from text and accepts non-photorealistic character illustrations (import_character_portrait with EXIF camera-tag blocking + AI vision screening). Real human photos, camera captures, face swaps, real public figures, and voice cloning are strictly blocked.
  • Non-blocking async video jobs + instant audio barks: create_npc_voice_line returns .mp3 audio in <3s, while 3–5 minute video renders (create_talking_video) return jobId immediately so MCP clients never time out.
  • Hashed keys: AvatarSay stores only the SHA-256 hash of avs_… keys. Revoke keys anytime in Dashboard.

Related Tools

License

MIT

NPM
avatarsay-mcp
Install Command
npm install avatarsay-mcp

Remote