mcp-social

mcp-social

Social Media Command Center for AI Agents

Generate cinema-quality social media graphics — carousels, post images, stories — directly from your AI agent. Manage brand kits and content calendars. Publish to LinkedIn and Instagram.

Built on the Model Context Protocol (MCP) standard. Works with Claude Desktop, Cursor, Windsurf, and any MCP-compatible client.

Features

• 9 MCP Tools — Discovery, Generation, Brand Kit, Content Planning, Publishing
• 21 Atmospheric Backgrounds — AI-generated, across 7 color families (gold, blue, green, rose, cyan, red, violet, neutral)
• 6 Layout Templates — cinematic, clean, bold, editorial, glass, minimal-data
• 5 Themes — dark-luxury, clean-minimal, bold-gradient, photo-overlay, corporate
• 10 Color Presets — gold, ocean-blue, emerald, rose-gold, copper, silver, neon-cyan, crimson, violet, white
• 11 Slide Types — title, content, stats, quote, cta, steps, features, comparison, social-proof, before-after, price
• 5 Output Formats — linkedin-square (1080x1080), linkedin-portrait (1080x1350), instagram-square (1080x1080), instagram-story (1080x1920), x-landscape (1200x675)
• Brand Kit Persistence — Save colors, fonts, logo once. Apply everywhere.
• Content Calendar — Plan posts with dates, platforms, status tracking
• PDF Export — Combined PDF of all carousel slides
• Accent Highlighting — Use *asterisks* around words for accent color glow

Quick Start

Installation

npm install
npm run build

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "social": {
      "command": "node",
      "args": ["/path/to/mcp-social/dist/server.js"],
      "env": {
        "WORKSPACE_STORAGE_ROOT": "/path/to/output"
      }
    }
  }
}

Docker

docker build -t mcp-social .
docker run -p 3101:3101 -e MCP_HTTP=1 -v /path/to/output:/data mcp-social

HTTP Mode

MCP_HTTP=1 PORT=3101 npm start

Configuration

Environment Variable	Default	Description
WORKSPACE_STORAGE_ROOT	$TMPDIR/mcp-social	Root path for workspace file storage
MCP_HTTP	-	Set to 1 for HTTP transport (StreamableHTTP)
PORT	3101	HTTP port (only when MCP_HTTP=1)

Tools

Discovery (1 tool)

Tool	Description
get_capabilities	Returns all available themes, backgrounds, formats, templates, slide types, color presets. Call this first.

Generation (3 tools)

Tool	Required Params	Description
create_carousel	workspaceId, topic, slides[]	Multi-slide carousel — individual PNGs + combined PDF
create_post_image	workspaceId, headline	Single branded social media image (PNG)
create_story	workspaceId, headline	Vertical story/reel image (1080x1920 default)

Brand Kit (2 tools)

Tool	Required Params	Description
save_brand_kit	workspaceId, name	Save brand identity (colors, fonts, logo, theme). Persists across sessions.
get_brand_kit	workspaceId	Load a saved brand kit by name

Content Planning (2 tools)

Tool	Required Params	Description
save_content_plan	workspaceId, name, posts[]	Save a content calendar with dates, platforms, status
get_content_plan	workspaceId	Load content plan with optional status/platform filters

Publishing (1 tool)

Tool	Required Params	Description
publish_post	workspaceId, platform, text	Publish to LinkedIn or Instagram (API credentials required)

Examples

Create a Carousel

{
  "workspaceId": "my-workspace",
  "topic": "AI Website Design",
  "slides": [
    { "type": "title", "title": "YOUR *WEBSITE* IS OUTDATED", "badge": "AI READY" },
    { "type": "stats", "stat": "305", "statLabel": "AI TOOLS", "title": "THE *FUTURE* IS HERE" },
    { "type": "content", "title": "WHAT WE *BUILD*", "items": ["AI Chatbots", "Smart Forms", "Auto SEO"] },
    { "type": "cta", "title": "LET'S *BUILD*", "content": "mysite.com" }
  ],
  "theme": "dark-luxury",
  "colorPreset": "gold",
  "backgrounds": ["neural-gold", "smoke-gold", "light-rays", "silk-dark"],
  "template": "cinematic",
  "logoText": "MY BRAND"
}

Save a Brand Kit

{
  "workspaceId": "my-workspace",
  "name": "My Company",
  "colors": {
    "accent": "#4a9eff",
    "background": "#0a0a0a",
    "text": "#f0f0f0"
  },
  "fonts": {
    "heading": "Inter",
    "body": "Open Sans"
  },
  "logoText": "ACME CO",
  "style": "clean-minimal"
}

Create a Single Post Image

{
  "workspaceId": "my-workspace",
  "headline": "WE JUST *LAUNCHED*",
  "badge": "NEW",
  "subline": "Something incredible is here",
  "format": "x-landscape",
  "theme": "bold-gradient",
  "colorPreset": "neon-cyan",
  "background": "neon-grid"
}

Design System

Templates

Template	Style	Best For
cinematic	Centered, gold accents, progress bar, vignette	Premium brands, luxury
clean	Left-aligned, Inter font, arrow markers, minimal	SaaS, tech companies
bold	Oversized type (140px+), thick progress bar	Conferences, high-impact
editorial	Playfair Display italic, thin dividers, frame border	Magazines, elegant brands
glass	Frosted glass card, backdrop blur, rounded corners	Modern, Apple-inspired
minimal-data	JetBrains Mono numbers, structured data rows	Stats, data-heavy content

Color Matching Guide

For best results, match colorPreset to background family:

Color Preset	Background Family	Example
gold	Gold backgrounds	neural-gold, smoke-gold
ocean-blue	Blue backgrounds	neural-blue, smoke-blue
emerald	Green backgrounds	neural-emerald, forest-mist
rose-gold	Rose backgrounds	silk-rose, neural-rose
neon-cyan	Cyan backgrounds	neon-grid
crimson	Red backgrounds	ember-glow
violet	Violet backgrounds	cosmic-violet
silver	Neutral backgrounds	steel-dark

Tips

• Use *asterisks* around words for accent color highlighting with glow effect
• UPPERCASE headlines for maximum visual impact
• 6-8 slides per carousel for best engagement
• Backgrounds cycle automatically if fewer backgrounds than slides
• Google Fonts are supported via brand kit (any heading + body font)

Requirements

• Node.js >= 18
• Chromium/Puppeteer — for HTML-to-PNG rendering (installed automatically via puppeteer package, or use system Chromium via PUPPETEER_EXECUTABLE_PATH)
• No database required — uses filesystem JSON storage

Development

npm run dev        # Watch mode (TypeScript)
npm run test       # Run tests (vitest)
npm run typecheck  # TypeScript strict check
npm run build      # Build to dist/

Architecture

src/
  server.ts           MCP server with 9 tool registrations (Zod schemas)
  handlers/index.ts   Tool handler routing + capabilities
  tools/
    renderer.ts       HTML/CSS -> Puppeteer -> PNG/PDF pipeline
    brandKit.ts       Brand kit CRUD (filesystem JSON)
    contentPlan.ts    Content calendar CRUD (filesystem JSON)
    publishPost.ts    Publishing to LinkedIn/Instagram
  schemas/index.ts    JSON Schema definitions (for non-Zod clients)
  __tests__/          19 tests (vitest)
assets/
  backgrounds/        21 atmospheric PNG backgrounds (45 MB)

License

MIT