ShortsMCP

Multi-platform Model Context Protocol (MCP) server for publishing short-form vertical videos across YouTube Shorts, TikTok, Instagram Reels, Telegram, VK Clips, Threads, X (Twitter), and Pinterest.

Features

• Multi-Platform Publishing: Cross-post vertical videos (9:16) to 8 social networks in a single call.

• Dual Publishing Engine: Supports official API / OAuth2 credentials and interactive browser sessions (Playwright).

• Smart Metadata Engine: Adapts titles, descriptions, hashtags, and character limits per platform algorithm.

• Video Preflight & Normalization: Validates aspect ratio, duration, and codecs with automated 9:16 vertical formatting via FFmpeg.

• Analytics & Performance Metrics: Retrieve views, likes, comments, shares, and engagement rates for published videos or channels.

• Encrypted Vault: OWASP-compliant AES encrypted credential storage with strict file permissions (0600).

• Queue & Scheduling: Persistent SQLite task queue with anti-flood jitter delays.

Related MCP server: TikVid MCP Server

Supported Platforms

Prerequisites

• Python 3.10 or higher

• FFmpeg installed and accessible in system PATH

Installation

git clone git@github.com:ivanchik-byte/ShortsMCP.git
cd ShortsMCP

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Copy the configuration template and set your platform credentials:

cp .env.example .env

Connecting to AI Agents & IDEs

ShortsMCP communicates via the standard stdio transport. Follow the tutorial below for your AI assistant of choice.

1. Claude Desktop

Add ShortsMCP to your claude_desktop_config.json:

{
  "mcpServers": {
    "shortsmcp": {
      "command": "/absolute/path/to/ShortsMCP/.venv/bin/python",
      "args": [
        "-m",
        "shortsmcp.server"
      ],
      "env": {
        "PYTHONPATH": "/absolute/path/to/ShortsMCP/src"
      }
    }
  }
}

Config file location by OS:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

Restart Claude Desktop. The hammer icon will appear showing ShortsMCP tools.

2. Cursor IDE

Option A: Project Configuration (Recommended)

Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "shortsmcp": {
      "command": "/absolute/path/to/ShortsMCP/.venv/bin/python",
      "args": ["-m", "shortsmcp.server"],
      "env": {
        "PYTHONPATH": "/absolute/path/to/ShortsMCP/src"
      }
    }
  }
}

Option B: Global Settings

1. Open Cursor Settings -> Features -> MCP Servers.

2. Click "Add New MCP Server".

3. Set Name to ShortsMCP, Type to command, and Command to:

   /absolute/path/to/ShortsMCP/.venv/bin/python -m shortsmcp.server

3. Windsurf / Cascade

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "shortsmcp": {
      "command": "/absolute/path/to/ShortsMCP/.venv/bin/python",
      "args": ["-m", "shortsmcp.server"],
      "env": {
        "PYTHONPATH": "/absolute/path/to/ShortsMCP/src"
      }
    }
  }
}

4. Custom Python AI Agents (LangChain, CrewAI, AutoGen, OpenAI SDK)

You can invoke ShortsMCP programmatically inside any agentic Python workflow using the official mcp client:

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def run_agent():
    server_params = StdioServerParameters(
        command="/absolute/path/to/ShortsMCP/.venv/bin/python",
        args=["-m", "shortsmcp.server"],
        env={"PYTHONPATH": "/absolute/path/to/ShortsMCP/src"}
    )
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            
            # List available tools
            tools = await session.list_tools()
            print("Connected tools:", [t.name for t in tools.tools])
            
            # Example: Request analytics across all channels
            stats = await session.call_tool("get_platform_analytics", arguments={})
            print("Channel Stats:", stats.content[0].text)

asyncio.run(run_agent())

5. Example Prompts for Your AI Agent

Once connected, you can instruct your AI assistant with natural language:

• "Check if my YouTube, TikTok, and Instagram accounts are connected and valid."

• "Validate /path/to/video.mp4 and convert it to 9:16 vertical format if it's horizontal."

• "Generate optimized captions and viral hashtags for a short video about 5 Python tips."

• "Publish /path/to/short.mp4 to YouTube Shorts, TikTok, and Telegram with title '5 Python Tips'."

• "Show me analytics (views, likes, comments) for my published videos on YouTube and Instagram."

• "Schedule /path/to/video.mp4 to post tomorrow at 18:00 UTC on all platforms."

MCP Tools Reference

CLI Commands

# Check platform credentials health
shortsmcp health

# Interactive login
shortsmcp login tiktok

# Validate video specs
shortsmcp validate /path/to/video.mp4 --normalize

# Fetch performance analytics
shortsmcp stats
shortsmcp stats --platform youtube --video-id <video_id>

# View publishing queue
shortsmcp queue

# Run MCP server manually
shortsmcp serve

Testing

pytest tests/ -v

Contacts

• Telegram Channel: https://t.me/ivanchik_byte

• Telegram Direct: https://t.me/ivanchikbyte

License

MIT License. See LICENSE for details.