Metadata-Version: 2.4
Name: spimov-mcp
Version: 0.6.0
Summary: Spimov MCP server — dub videos via Claude Desktop / Claude Code / any MCP client
Author-email: Spimov <support@spimov.com>
License: MIT License
        
        Copyright (c) 2026 Spimov
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://spimov.com
Project-URL: Repository, https://github.com/spimov-ai/spimov-mcp
Project-URL: Issues, https://github.com/spimov-ai/spimov-mcp/issues
Keywords: mcp,model-context-protocol,dubbing,video,subtitles,ai,claude
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0.0
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Dynamic: license-file

# spimov-mcp

MCP server for Spimov — dub videos via Claude Desktop / Claude Code / any MCP client.

Two transports:
- **stdio** — runs locally, spawned by your MCP client, authenticated with `SPIMOV_API_KEY` env var. Supports local file upload (`create_dub`).
- **HTTP** — long-lived server (we host at `mcp.spimov.com`), authenticated per-request with `Authorization: Bearer spk_live_...` (or `?api_key=`). Exposes both Streamable HTTP (`/mcp`, current spec) and legacy SSE (`/sse`). URL-only — no local file upload.

Both transports are thin wrappers over the public REST API at `https://spimov.com/api/v1`. The same API key, the same daily request quota.

---

## 1. Get an API key

Sign in at https://spimov.com → **Settings → API keys → Create new key**. Copy the `spk_live_...` token shown once.

## 2a. Use via stdio (Claude Desktop)

Install:

```bash
pip install spimov-mcp
```

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "spimov": {
      "command": "spimov-mcp",
      "env": {
        "SPIMOV_API_KEY": "spk_live_xxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

Restart Claude Desktop. The "spimov" MCP server should appear; ask Claude to "dub /Users/me/Movies/clip.mp4 into Turkish using Spimov".

## 2b. Use via HTTP (Claude Code / Claude web / other clients)

Self-hosted: `MCP_PORT=8001 spimov-mcp-http`. Hosted endpoints:
- Streamable HTTP (recommended): `https://mcp.spimov.com/mcp`
- Legacy SSE: `https://mcp.spimov.com/sse`

**Claude Code / config-file clients** (header auth):

```json
{
  "mcpServers": {
    "spimov": {
      "url": "https://mcp.spimov.com/mcp",
      "headers": {
        "Authorization": "Bearer spk_live_xxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

**Claude web** (claude.ai → Settings → Connectors → *Add custom connector*): the
UI only takes a URL, so put the key in the query string:

```
https://mcp.spimov.com/mcp?api_key=spk_live_xxxxxxxxxxxxxxxxxxxxxxxx
```

> The key travels in the URL (stored in your connector config). Treat it like a
> password and rotate it from **Settings → API keys** if it leaks. Local file
> tools (`create_dub`, `download_video`) are unavailable here — use `dub_youtube`
> to dub, and `get_download_url` to get a clickable browser download link for the
> finished MP4.

## 3. Tools

| Tool | Purpose |
|---|---|
| `create_dub` | Upload a local file and queue a dubbing job (stdio only). |
| `dub_youtube` | Dub a YouTube URL server-side; optional auto-upload to a channel. |
| `get_job_status` | Poll a job (queued / processing / review / completed / failed). |
| `list_jobs` | Recent jobs for the account. |
| `list_segments` | Transcript segments (text, speaker, emotion, timing) of a job. |
| `update_segment` | Edit one segment's text/emotion/speaker/skip and resynth. |
| `remix_video` | Re-render audio mix / subtitles / lipsync without re-dubbing. |
| `download_video` | Save the finished MP4 locally (**stdio only**). |
| `get_download_url` | Get a shareable, time-limited browser download link for the MP4 (use this over HTTP/web). |
| `get_subtitles` | Fetch SRT/VTT (any embedded language). |
| `upload_to_youtube` | Publish (or retry) a finished job to a connected channel. |
| `cancel_job` | Cancel/delete. |
| `list_languages` | Source + target language list (17 target languages). |
| `get_quota` | Current minute & request usage vs. plan limits. |

Dubbing tools (`create_dub`, `dub_youtube`) accept an optional `tts_provider`: `xtts` (quality voice, **default**), `chatterbox` (emotion voice), or `elevenlabs` (paid).

## 4. Override the API base (dev)

```bash
SPIMOV_API_BASE=http://localhost:8000/api/v1 spimov-mcp
```
