# 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.

## Supported Platforms

| Platform | Integration | Video Constraints |
| :--- | :--- | :--- |
| YouTube Shorts | YouTube Data API v3 (OAuth2) | 9:16 / 1:1, up to 3 min |
| TikTok | Content Posting API v2 / Web Session | 9:16, up to 10 min |
| Instagram Reels | Meta Graph API / Web Session | 9:16, up to 90 sec |
| Telegram | Telegram Bot API (sendVideo) | 9:16 / Any, up to 2 GB |
| VK Clips | VK Open API (shortVideos.create) | 9:16, up to 3 min |
| Threads | Threads Video Publishing API | 9:16 / 1:1, up to 5 min |
| X (Twitter) | X API v2 Chunked Media Upload | 9:16 / 16:9, up to 140 sec |
| Pinterest | Pinterest API v5 (Video Pins) | 9:16 / 2:3, up to 15 min |

## Prerequisites

- Python 3.10 or higher
- FFmpeg installed and accessible in system PATH

## Installation

```bash
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:

```bash
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`:

```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:

```json
{
  "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:
   ```bash
   /absolute/path/to/ShortsMCP/.venv/bin/python -m shortsmcp.server
   ```

### 3. Windsurf / Cascade

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

```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:

```python
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

| Tool | Parameters | Description |
| :--- | :--- | :--- |
| `publish_short` | `video_path`, `title`, `description`, `platforms`, `tags`, `hashtags`, `privacy`, `thumbnail_path`, `jitter_seconds` | Cross-post a short video to one or all platforms. |
| `schedule_short` | `video_path`, `title`, `scheduled_at_iso`, `description`, `platforms`, `tags`, `hashtags`, `privacy` | Queue a video for future scheduled publishing. |
| `validate_video` | `video_path`, `target_platforms`, `auto_normalize` | Inspect media specs and optionally auto-convert to 9:16. |
| `generate_metadata` | `title`, `description`, `tags`, `hashtags`, `target_platforms` | Generate platform-tailored titles, captions, and tags. |
| `check_platforms_status` | None | Check connection and authentication health for all platforms. |
| `login_platform` | `platform`, `timeout_seconds` | Run interactive browser or OAuth login for a platform. |
| `list_queue` | `status`, `limit` | View tasks in the SQLite publishing queue. |
| `get_video_analytics` | `video_id`, `platform` | Fetch views, likes, comments, shares, and engagement rate for a short video. |
| `get_platform_analytics` | `platforms` | Fetch overview channel/account stats (views, followers, videos) across platforms. |

## CLI Commands

```bash
# 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

```bash
pytest tests/ -v
```

## Contacts

- Telegram Channel: https://t.me/ivanchik_byte
- Telegram Direct: https://t.me/ivanchikbyte

## License

MIT License. See [LICENSE](LICENSE) for details.