social-commerce-intelligence-mcp

Social Commerce Intelligence MCP

Core Problem

Creator affiliate, video, and shop revenue data is siloed across TikTok, Instagram, Pinterest, YouTube, and Shopify.

What This Server Provides

This folder contains a production-minded MCP server scaffold with typed JSON tool responses, connector health metadata, OAuth-oriented configuration, rate-limit guards, stable error envelopes, and deterministic demo data until live vendor integrations are attached.

This server has received a production pass. It now includes local creator and social commerce models for creator ROI, video conversion, trending products, affiliate commissions, platform revenue, and underperforming creator detection.

Connectors

• TikTok Shop API via OAuth scope seller.read; env prefix TIKTOK_SHOP
• TikTok for Business API via OAuth scope advertiser.read; env prefix TIKTOK_BUSINESS
• Instagram Graph API via OAuth scope instagram_basic; env prefix INSTAGRAM
• Pinterest Shopping API via OAuth scope pins:read; env prefix PINTEREST
• YouTube Data API via OAuth scope youtube.readonly; env prefix YOUTUBE
• Shopify Admin API via OAuth scope read_orders; env prefix SHOPIFY

MCP Tools

• get_creator_roi_report - Creator revenue, commission, CAC, and margin.
• get_top_converting_videos - Rank videos by conversion quality.
• get_trending_products - Trending shop products by niche.
• get_affiliate_commissions_summary - Commission liability and payout status.
• get_social_commerce_revenue_by_platform - Revenue by social commerce platform.
• identify_underperforming_creators - Creators needing coaching or pause.

Current Local Capabilities

• Calculates creator revenue, commission, total cost, gross profit, contribution profit, ROI, and conversion rate.
• Ranks videos by click-to-order conversion and revenue per thousand views.
• Returns trending products by category and region.
• Summarizes affiliate commission liability and creators held for payout validation.
• Compares social commerce revenue by TikTok, Instagram, YouTube, and Pinterest.
• Detects underperforming creators by order count, conversion rate, and contribution profit.

Test

python -m pytest .\tests -q -p no:cacheprovider

Partial Platform Support

Customers only need to connect the social-commerce platforms they actually use. Missing TikTok Shop, TikTok Business, Instagram, Pinterest, YouTube, Shopify, or affiliate credentials do not prevent the server from starting or running local intelligence tools.

Use get_live_connector_status to see configured connectors. Use test_tiktok_shop_connection, test_affiliate_connection, and test_social_content_connection for read-only live smoke checks when those platforms are connected.

Running Locally

powershell python -m venv .venv .\.venv\Scripts\pip install -e . .\.venv\Scripts\python -m social_commerce_intelligence_mcp.server

Claude Desktop Config

json { "mcpServers": { "social-commerce-intelligence": { "command": "python", "args": ["-m", "social_commerce_intelligence_mcp.server"], "cwd": "D:\CUSTOMS\EARNALL\MCP Servers\07-social-commerce-intelligence" } } }

Production Checklist

• Create OAuth 2.1 apps for each connector and set *_CLIENT_ID plus *_CLIENT_SECRET.
• Store refresh tokens in a secrets manager, never in repo files.
• Replace deterministic demo rows in server.py with API adapter calls.
• Persist raw snapshots and normalized warehouse tables for trend analysis.
• Add integration tests with recorded fixtures for every connector.
• Validate every tool in MCP Inspector before publishing.
• Deploy with a /health route through FastMCP streamable HTTP on Railway or Render.