musepublisher-mcp

Model Context Protocol (MCP) server exposing MusePublisher persona and brand configuration to AI assistants.

An AI assistant with this MCP can fully configure an artist end-to-end: create a persona, define brand guardrails, color palette, approved symbols, wardrobe, companions, locations, voice samples, hashtag pools, prompt directives, content definitions, and caption styles.

Status: v0.2 (L1 + L2 + L3)

• L1 + L2: read + brand configuration writes
• L3: content generation (images, videos, captions, content management)

Future sub-project:

• L4: scheduling, campaigns, and Instagram publishing

Installation

Requirements

• Node.js 18+
• A MusePublisher Supabase project with service-role key

Install

npm install -g musepublisher-mcp

Or use via npx (no install needed):

MUSEPUBLISHER_SUPABASE_URL=... MUSEPUBLISHER_SUPABASE_SERVICE_ROLE_KEY=... npx -y musepublisher-mcp

Configure in Claude Desktop

Edit %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "musepublisher": {
      "command": "npx",
      "args": ["-y", "musepublisher-mcp"],
      "env": {
        "MUSEPUBLISHER_SUPABASE_URL": "https://your-project.supabase.co",
        "MUSEPUBLISHER_SUPABASE_SERVICE_ROLE_KEY": "eyJ..."
      }
    }
  }
}

Restart Claude Desktop. Tools appear in the tool drawer.

Environment variables

• MUSEPUBLISHER_SUPABASE_URL — your Supabase project URL (e.g., https://abc123.supabase.co)
• MUSEPUBLISHER_SUPABASE_SERVICE_ROLE_KEY — service-role key (NOT the anon key). Find it in Supabase dashboard → Project Settings → API.
• GEMINI_API_KEY — required for L3 generation tools (image, video, caption pipeline). Get one at https://aistudio.google.com/app/apikey.

Security: The service-role key grants full database access. Keep it local, never commit it, and never share the config file.

Tools

61 tools across 10 categories.

Personas

• list_personas — List all personas (artists) in MusePublisher, returning a summary of each including id, name, bio, color, gender, age_range, location, and created_at.
• get_persona — Fetch a persona's full state including all sub-entities (references, wardrobe, hairstyles, companions, locations, voice samples, hashtag pools, brand guardrails, prompt directives, content definitions, and caption styles) in a single call.
• create_persona — Create a new persona (artist), automatically seeding default brand definitions from global templates. Returns the created persona.
• update_persona — Update a persona's metadata: name, bio, color, gender, age_range, location, backstory, personality_traits, visual_mannerisms, authentic_aesthetic, or higgsfield_soul_id.
• delete_persona — Delete a persona and ALL associated data (cascading). Irreversible — requires explicit confirm: true.

References

• list_references — List reference images for a persona, returning id, name, storage_path, public_url, mime_type, and any linked companion_id, wardrobe_item_id, or location_id.

Brand identity

• add_brand_guardrail — Add a brand rule constraining content for this persona (categories: visual, caption, prompt; rule types: forbidden, required, limit).
• update_brand_guardrail — Update an existing brand guardrail: category, rule_type, value, description, is_enabled, or sort_order.
• delete_brand_guardrail — Permanently delete a brand guardrail rule.
• set_color_palette — Replace the persona's brand color palette with an array of {role, hex, label} entries — injected into every image generation prompt.
• add_approved_symbol — Add an approved visual symbol to the persona's brand vocabulary, with name, description, and usage guidance injected into the prompt writer's meta-prompt.
• update_approved_symbol — Update an approved symbol by its array index (name, description, or usage).
• delete_approved_symbol — Delete an approved symbol by its array index.

Prompt directives

• add_prompt_directive — Add a prompt directive (an instruction text block in the meta-prompt sent to Gemini Flash), with optional variable_bindings that gate inclusion on resolved values.
• update_prompt_directive — Update an existing prompt directive: label, content, description, probability, section_header, variable_bindings, is_enabled, or sort_order.
• delete_prompt_directive — Permanently delete a prompt directive.

Wardrobe & hairstyles

• add_wardrobe_item — Add a wardrobe item (outfit) to a persona; description is injected into generation prompts to specify what the artist wears.
• update_wardrobe_item — Update a wardrobe item's label, description, or category.
• delete_wardrobe_item — Delete a wardrobe item.
• add_hairstyle — Add a hairstyle option for a persona; description is injected into generation prompts to specify the hairstyle.
• update_hairstyle — Update a hairstyle's label or description.
• delete_hairstyle — Delete a hairstyle.

Companions & locations

• add_companion — Add a companion (person, pet, or collaborator in the artist's world) to the persona; description is injected into generation prompts when the companion is selected.
• update_companion — Update a companion's name, role, or description.
• delete_companion — Delete a companion.
• add_location — Add a location (setting) to a persona (types: indoor, outdoor, studio, vehicle, other); description is injected into generation prompts.
• update_location — Update a location's name, type, description, or category.
• delete_location — Delete a location.
• add_location_category — Add a location category for grouping locations (e.g., "Home" → Bathroom, Bedroom, Kitchen) to enable random picks at generation time.
• update_location_category — Update a location category's name or description.
• delete_location_category — Delete a location category; locations in the category are not deleted, their category_id becomes null.

Voice & hashtags

• add_voice_sample — Add a voice sample — example text in the artist's voice used by the caption generator to match tone.
• update_voice_sample — Update a voice sample's label or content.
• delete_voice_sample — Delete a voice sample.
• add_hashtag_pool — Add a hashtag pool (global or scoped to a content category) with a random subset appended to generated captions up to max_per_post.
• update_hashtag_pool — Update a hashtag pool's name, hashtags, max_per_post, category_id, is_enabled, or sort_order.
• delete_hashtag_pool — Delete a hashtag pool.

Content definitions

• add_content_category — Add a content category (e.g., "Portrait", "Environment") with a prompt_template injected at generation time; slug is the stable identifier.
• update_content_category — Update a content category; set include_character=false to skip artist reference images for environment or detail shots.
• delete_content_category — Delete a content category.
• add_content_mood — Add a content mood (e.g., "Reverent", "Melancholic"); the fragment text is injected into the meta-prompt when this mood is selected.
• update_content_mood — Update a content mood's slug, label, fragment, example_prompts, or sort_order.
• delete_content_mood — Delete a content mood.
• add_content_focus — Add a content focus for framing direction (e.g., "Face close-up", "Full body"); the fragment text is injected into the meta-prompt.
• update_content_focus — Update a content focus.
• delete_content_focus — Delete a content focus.
• add_content_attention_intent — Add a content attention/gaze intent (e.g., "Direct eye contact", "Looking away"); the fragment text is injected into the meta-prompt.
• update_content_attention_intent — Update a content attention intent.
• delete_content_attention_intent — Delete a content attention intent.
• add_caption_style — Add a caption style with an instruction sent directly to Gemini for tone (e.g., "Write poetic fragments, no hashtags, no emoji, max 150 chars").
• update_caption_style — Update a caption style's label, instruction, is_enabled, or sort_order.
• delete_caption_style — Delete a caption style.

Generated content (read-only)

• list_content — List generated content for a persona, paginated, with optional filters for status (draft/approved/rejected/published) and type (image/video).
• get_content — Get a single generated content row including the full prompt, meta_prompt, caption, caption_variants with violation details, and all metadata.

Generation (L3)

• build_prompt_preview — Preview the meta-prompt + generated prompt + brand suffix WITHOUT generating an image. Useful for debugging directives or deciding whether to write a better prompt yourself.
• generate_image — Generate an image. PREFERRED: provide your own prompt (you have richer artist context). Fallback: omit prompt + provide category_id for the directive pipeline. Brand suffix auto-appended. References auto-selected based on wardrobe/companion/location IDs.
• generate_video — Generate a 2-8s video via Veo. Same dual-path design as generate_image. Blocks 1-5 minutes during polling. First reference is used as start image.
• generate_caption_variants — FALLBACK — generate 3 caption variants via the directive pipeline using voice samples + caption style.
• set_content_caption — PREFERRED for captions. Save a caption you wrote. Optional alternative variants. Validation against guardrails returned as warnings (non-blocking).
• update_content — Update a content row's status (draft/approved/rejected) or swap which caption variant is accepted.
• delete_content — Delete a content row AND its storage file (best-effort).

Safety

• delete_persona requires explicit confirm: true to prevent accidental cascading deletes.
• No bulk destructive tools — individual deletes only.
• Write tools return the affected row so the AI can verify outcomes.
• generated_content is read-only via MCP — preserves integrity of generation history.
• The MCP makes no external API calls (no Gemini, Instagram, etc.) — only Supabase.

Scope limitations

• Reference image upload is not supported (use the MusePublisher UI for uploads).
• No scheduling, campaigns, or Instagram publishing tools yet (planned for L4).
• Provider selection (Gemini/Grok/Higgsfield) is not exposed as a tool param — uses the env-configured default.
• Generation blocks synchronously; expect 5-30s for images, 1-5min for videos.

License

UNLICENSED — private use only.