@socialai/website-mcp

Model Context Protocol server for the Social AI Website Builder.

Use Social AI from Claude, OpenAI Codex, Cursor, Windsurf, VS Code, or any MCP-compatible client to create websites, edit pages, manage shops, upload media, configure payments, inspect analytics, and publish live sites.

What Users Can Do

• Create a blank website or shop.
• Create a website from a Social AI template.
• Browse block types with reference links before adding headers, heroes, promo/ad sections, product rows, forms, and footers.
• Use setup presets for shop categories, variants, header menus, footer columns, contact pages, and product CSVs.
• Edit pages and blocks.
• Generate website copy, page sections, and themes with AI.
• Manage products, variants, categories, CSV import/export, discounts, and orders.
• Upload and host images.
• Configure country, currency, payment provider, and public site settings.
• Check preview, domain, analytics, leads, snapshots, and media limits.
• Publish a site when the account has an active package website slot.

Requirements

• Node.js 18 or newer.
• A Social AI account.
• A Social AI API key from Settings -> API Keys.

Quick Start

Add this MCP server to your AI client:

{
  "mcpServers": {
    "socialai-websites": {
      "command": "npx",
      "args": ["-y", "@socialai/website-mcp"],
      "env": {
        "SOCIALAI_API_KEY": "sai_user_xxxxx",
        "SOCIALAI_API_URL": "https://socialai.one"
      }
    }
  }
}

Then restart your AI client and try:

Help me create a Social AI website. Ask me one question at a time.

The MCP includes get_started, get_store_setup_preset, generate_product_csv_template, and a socialai_start_website prompt. Good AI clients can use those to guide the user through a friendly setup flow instead of dumping raw JSON.

For template browsing, ask for a small shortlist:

Show me 5 shop templates with preview links for a South African fashion store.

For block browsing, ask for focused options:

Show me 8 hero and header blocks with reference links.

Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "socialai-websites": {
      "command": "npx",
      "args": ["-y", "@socialai/website-mcp"],
      "env": {
        "SOCIALAI_API_KEY": "sai_user_xxxxx",
        "SOCIALAI_API_URL": "https://socialai.one"
      }
    }
  }
}

OpenAI Codex

Add to ~/.codex/config.json:

{
  "mcpServers": {
    "socialai-websites": {
      "command": "npx",
      "args": ["-y", "@socialai/website-mcp"],
      "env": {
        "SOCIALAI_API_KEY": "sai_user_xxxxx",
        "SOCIALAI_API_URL": "https://socialai.one"
      }
    }
  }
}

Cursor or Windsurf

Add to .cursor/mcp.json or the Windsurf MCP settings:

{
  "mcpServers": {
    "socialai-websites": {
      "command": "npx",
      "args": ["-y", "@socialai/website-mcp"],
      "env": {
        "SOCIALAI_API_KEY": "sai_user_xxxxx",
        "SOCIALAI_API_URL": "https://socialai.one"
      }
    }
  }
}

VS Code

Add to .vscode/settings.json:

{
  "mcp": {
    "servers": {
      "socialai-websites": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@socialai/website-mcp"],
        "env": {
          "SOCIALAI_API_KEY": "sai_user_xxxxx",
          "SOCIALAI_API_URL": "https://socialai.one"
        }
      }
    }
  }
}

Tool Groups

Getting Started

• get_started
• get_store_setup_preset
• generate_product_csv_template
• list_blocks
• Prompt: socialai_start_website
• Resources: socialai://mcp/getting-started, socialai://mcp/workflows/create-website

Websites

• list_websites
• create_website
• get_website
• update_website
• set_package_slot_active
• delete_website
• list_templates
• create_website_from_template
• publish_website
• set_domain
• get_preview_url
• get_domain_status
• verify_domain

Pages and Navigation

• list_pages
• get_page
• create_page
• update_page_blocks
• delete_page
• reorder_pages
• duplicate_page
• manage_navigation

Block Catalog

• list_blocks

Use this before adding sections when the user wants to choose a block visually or by name. Each result includes type, label, group, keywords, and referenceUrl.

AI and Theme

• generate_content
• get_theme
• apply_theme

Store, Products, Orders, and Discounts

• list_products
• add_product
• update_product
• delete_product
• list_categories
• create_category
• rename_category
• assign_category
• export_products_csv
• import_products_csv
• list_variants
• add_variants
• clear_variants
• list_orders
• get_order
• update_order_status
• fulfill_order
• list_discounts
• create_discount

Media

• get_media_limits
• upload_image
• upload_image_file

Payments and Settings

• get_payment_settings
• configure_payments
• get_site_settings
• configure_site_settings

Analytics, Leads, Snapshots, and Support

• get_traffic_summary
• list_leads
• list_snapshots
• restore_snapshot
• revert_to_published
• report_issue

Example Prompts

Help me create a Social AI website. Ask me one question at a time, then recommend templates.

Show me 5 premium shop templates with preview links for a South African fashion store.

Create a website from the best template for a premium dental clinic in Johannesburg.

List my websites, make the newest one the active package-slot website, and show me the preview URL.

Import this product CSV, upload the image URLs, create categories, and configure South African payments.

Export only the demo products with source columns, then replace the demo products with my real CSV.

Check my store orders, list open leads, and summarize the last 30 days of traffic.

Duplicate the About page, rename it Our Story, update the navigation, and publish when I confirm.

Show me promo/ad style blocks with reference links, then add the one I choose to the homepage.

Template Browsing Without Huge Output

list_templates supports filters so AI clients do not need to load every template:

• limit and offset for pagination.
• q for natural search text such as fashion, coffee, law, or skincare.
• projectType as website or shop.
• category for category/tag filtering.
• premium for premium/free filtering.
• includePages=false and summaryOnly=true for short chat output.

Each result includes a previewUrl so the user can click and inspect the template before choosing it.

Product CSV and Demo Products

Template shops can include demo products so the store looks complete before the seller adds their own catalog. Those demo rows are tagged separately from seller-imported rows.

• Use generate_product_csv_template to create a fillable product CSV for the chosen store type.
• Use export_products_csv with scope: "demo" to download only template demo products.
• Use export_products_csv with scope: "user" to download only seller/imported products.
• Use includeSource: true when the AI or admin needs to see whether a row is demo or user-owned.
• Use import_products_csv with replaceDemoProducts: true when the seller confirms they want to delete the demo catalog and replace it with their real products.

The import endpoint currently imports the core product fields. Variant/spec/FAQ planning columns from generate_product_csv_template should be handled by follow-up MCP actions such as add_variants and update_product.

Safeguards and Entitlements

The MCP respects Social AI plan rules:

• API keys must have the right scopes.
• Paid package slots control publishing, commerce, payments, and custom-domain power.
• Draft sites can exist without being assigned to a paid package slot.
• Media uploads are checked against storage, monthly upload count, file size, dimensions, and image type limits.
• AI generation checks plan access, rate limits, and credit billing.
• Expired/free accounts can read where allowed, but write, publish, commerce, AI, and custom-domain tools can be blocked by plan state.
• Project-scoped keys can only access their pinned project.

When a tool is blocked, the server returns an error code such as:

• mcp_access_denied
• website_edit_mode_denied
• inactive_package_slot
• active_package_slot_limit
• published_site_limit
• media_storage_limit
• monthly_media_upload_limit
• ai_provider_failed

Country-Aware Payments

Use configure_payments with a country code:

Configure this shop for South Africa.

The tool can set country=ZA, currency=ZAR, and recommend providers such as Paystack, PayFast, and Ozow. Payment provider secret keys are not accepted through MCP; they must be entered in the Social AI dashboard.

Local Testing

PowerShell:

cd C:\sai\SaiApp\mcp
$env:SOCIALAI_API_URL = "http://localhost:3000"
$env:SOCIALAI_API_KEY = "sai_user_xxxxx"
node test-local.mjs

Do not paste the PS C:\...> prompt itself. Only paste the commands.

Publishing a New npm Version

cd C:\sai\SaiApp\mcp
npm login
npm version patch --no-git-tag-version
npm run build
npm pack --dry-run
npm publish --access public
npm view @socialai/website-mcp version

The npm package only updates the client-side MCP server. The Social AI web app must also be deployed so the matching /api/mcp-api/* routes exist in production.

Environment Variables

| Variable | Required | Description | | --- | --- | --- | | SOCIALAI_API_KEY | Yes | User or project API key from Social AI. | | SOCIALAI_API_URL | No | Social AI API base URL. Defaults to https://socialai.one. |

License

MIT