# Submagic MCP Server

mcp-name: io.github.sidart10/submagic-mcp-server

Connect your AI assistant to Submagic's powerful video editing API. Create viral short-form content, add AI captions in 107 languages, and automate your video production workflow directly from Claude or any MCP-compliant client.

## Table of Contents

- [Features](#features)
- [Getting Started](#getting-started)
  - [Prerequisites](#prerequisites)
  - [Installation](#installation)
  - [Configuration](#configuration)
- [Usage Examples](#usage-examples)
  - [Create Video with AI Captions](#create-video-with-ai-captions)
  - [Generate TikTok Clips from YouTube](#generate-tiktok-clips-from-youtube)
  - [Export for Social Media](#export-for-social-media)
- [Available Tools](#available-tools)
- [Limitations](#limitations)
- [Contributing](#contributing)
- [License](#license)

## Features

*   **Global Reach:** Automatic AI captions with 98%+ accuracy in 107 languages.
*   **Dynamic Editing:** Magic zooms and auto-inserted B-rolls with configurable coverage.
*   **Smart Cleanup:** Automated silence removal (3 speeds) and filler word removal ("um", "uh").
*   **Content Repurposing:** Convert YouTube videos into viral short-form clips (TikTok, Reels, Shorts).
*   **Professional Styling:** Access 30+ trending templates (Hormozi, Beast, Sara).
*   **Optimized Exports:** Ready-to-post formats for all major platforms (9:16, 1:1, 16:9, 4:5).

## Getting Started

### Prerequisites

- Python 3.10 or higher
- A Submagic API Key (Get one at [Submagic.co](https://app.submagic.co/signup))

### Installation

**Option 1: Install via PyPI (Recommended)**

```bash
pip install submagic-mcp-server
```

**Option 2: Install from Source**

```bash
git clone https://github.com/sidart10/submagic-mcp-server.git
cd submagic-mcp-server
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

### Configuration

1.  **Get your API Key:**
    Sign up at [submagic.co](https://app.submagic.co/signup) to retrieve your API key.

2.  **Configure Claude Desktop:**
    Add the server definition to your `claude_desktop_config.json` file.

    *If installed via PyPI:*
    ```json
    {
      "mcpServers": {
        "submagic": {
          "command": "python",
          "args": ["-m", "submagic_mcp"],
          "env": {
            "SUBMAGIC_API_KEY": "sk-your-api-key-here"
          }
        }
      }
    }
    ```

    *If installed from source (use absolute paths):*
    ```json
    {
      "mcpServers": {
        "submagic": {
          "command": "/absolute/path/to/venv/bin/python",
          "args": ["/absolute/path/to/submagic_mcp.py"],
          "env": {
            "SUBMAGIC_API_KEY": "sk-your-api-key-here"
          }
        }
      }
    }
    ```

3.  **Restart Claude Desktop:**
    Relaunch the application to load the new server.

## Usage Examples

Here are common workflows you can automate:

### Create Video with AI Captions

Upload a raw video and apply professional styling with captions.

```python
submagic_create_project(
    title="Product Demo Launch",
    language="en",
    video_url="https://example.com/raw-video.mp4",
    template_name="Hormozi 2",
    remove_silence_pace="fast",
    magic_zooms=True
)
```

### Generate TikTok Clips from YouTube

Turn a long-form YouTube video into multiple engaging shorts.

```python
submagic_create_magic_clips(
    title="Podcast Highlights",
    youtube_url="https://youtube.com/watch?v=your-video-id",
    language="en",
    min_clip_length=30,
    max_clip_length=60
)
```

### Export for Social Media

Finalize and export your project in the perfect format for Instagram Reels.

```python
submagic_export_project(
    project_id="your-project-uuid",
    width=1080,
    height=1920,
    fps=30
)
```

## Available Tools

| Tool | Description | Rate Limit |
|------|-------------|------------|
| `submagic_list_languages` | Get list of supported languages (107+) | 1000/hr |
| `submagic_list_templates` | Get available video styling templates | 1000/hr |
| `submagic_create_project` | Create a new video project with AI features | 500/hr |
| `submagic_get_project` | Get project details, status, and download URL | 500/hr |
| `submagic_update_project` | Update settings (silence, b-rolls) after creation | 100/hr |
| `submagic_export_project` | Render and export the final video | 500/hr |
| `submagic_create_magic_clips` | Generate shorts from YouTube videos | 500/hr |

## Limitations

*   **Input:** Videos must be publicly accessible URLs.
*   **Size:** Maximum file size is 2GB.
*   **Duration:** Maximum video duration is 2 hours.
*   **Formats:** Supports MP4 and MOV.
*   **Performance:** `remove_bad_takes` adds 1-2 minutes to processing time.
*   **API Coverage:** Some dashboard features are not yet available via API. See `docs/API_LIMITATIONS_DISCOVERED.md` for details.

## Contributing

We welcome contributions! Please follow these steps:

1.  Fork the repository.
2.  Create a feature branch: `git checkout -b feature/new-tool`.
3.  Install development dependencies: `pip install -r requirements.txt`.
4.  Run tests to ensure everything works: `python -m pytest tests/`.
5.  Submit a Pull Request describing your changes.

See `docs/development-guide.md` for more detailed instructions.

## License

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

## Resources

*   [Submagic API Documentation](https://docs.submagic.co)
*   [Model Context Protocol (MCP)](https://modelcontextprotocol.io)