golpo-mcp
Model Context Protocol server for the Golpo AI video API. Generate, list, and download Golpo videos from any MCP-compatible client — Claude Desktop, Claude Code, Cursor, Continue, Zed, Windsurf, or your own.
👋 End-user, not a developer? Read the friendly walk-through: Use Golpo from your favorite AI tool — step-by-step setup for Cursor, Claude Code, VS Code, Claude Desktop, and Visual Studio with troubleshooting and sample prompts.
What it does
Wraps the Golpo Video API as a set of MCP tools so an LLM (or any MCP client) can generate and manage videos directly. Same underlying API as the Golpo Claude Code skill; this is the broader-reach packaging.
Install
Run-without-install (recommended)
If you have uv:
uvx golpo-mcp
uvx downloads the package on first run, caches it, and re-uses the cache
on subsequent calls.
Install into your environment
pip install golpo-mcp
# or
uv pip install golpo-mcp
Then run with golpo-mcp or python -m golpo_mcp.
From source (for development)
git clone https://github.com/Golpo-AI/golpo-mcp.git
cd golpo-mcp
uv sync # or: pip install -e .[dev]
uv run python -m golpo_mcp
Configure your MCP client
Claude Desktop
~/Library/Application Support/Claude/claude_desktop_config.json (macOS):
{
"mcpServers": {
"golpo": {
"command": "uvx",
"args": ["golpo-mcp"],
"env": {
"GOLPO_API_KEY": "your-key-here"
}
}
}
}
Restart Claude Desktop after editing. The 6 Golpo tools appear in the tools menu.
Claude Code
claude mcp add golpo --env GOLPO_API_KEY=your-key -- uvx golpo-mcp
Or by editing ~/.claude.json directly:
{
"mcpServers": {
"golpo": {
"command": "uvx",
"args": ["golpo-mcp"],
"env": { "GOLPO_API_KEY": "your-key" }
}
}
}
Cursor
~/.cursor/mcp.json:
{
"mcpServers": {
"golpo": {
"command": "uvx",
"args": ["golpo-mcp"],
"env": { "GOLPO_API_KEY": "your-key" }
}
}
}
Any other MCP client
Use the same shape. The server speaks stdio MCP — no special transport.
API key
Resolution order:
GOLPO_API_KEYenv var (preferred in client configs above)~/.golpo/api_keyfile with mode0600
The file location is shared with the Golpo Claude Code skill, so users who already have that skill authenticated don't need to re-enter the key.
Get a key at video.golpoai.com.
Tool catalog (v0.1.0)
| Tool | What it does |
|---|---|
generate_video |
Submit a job (prompt / script / audio / docs), poll until done, optionally download the MP4. Returns {job_id, video_id, video_url, video_file, status, params_used}. |
upload_file |
Upload an audio / document / image (≤ 15 MB). Two-step: multipart POST + S3 PUT. Returns {file_url, …}. Pass file_url into generate_video. |
list_videos |
List the caller's recent videos. Args: limit, offset. |
get_video |
Fetch metadata for one video; optionally re-download the MP4. Args: video_id, download, output_dir. |
check_status |
One-shot status check on an in-flight job_id. |
status |
Diagnostic: report whether an API key is configured and which source (env / file / none). Doesn't return the key. |
Every tool returns a JSON-serializable dict. Errors come back as
{error: "...", message: "..."} instead of crashing the server.
Examples
In a client connected to the server, an LLM might call:
// Plain prompt, auto-download
generate_video({ "prompt": "Why is the sky blue?", "timing": "0.5" })
// Custom script + Canvas Sharpie + stylus cursor
generate_video({
"prompt": "Photosynthesis explained simply",
"new_script": "Plants are nature's solar panels...",
"use_2_0_style": true,
"image_style": "marker",
"pen_style": "stylus",
"timing": "0.5"
})
// Two-step upload + generate from PDF
upload_file({ "path": "/Users/me/report.pdf" })
// -> { "file_url": "https://...", ... }
generate_video({
"prompt": "Summarize this report",
"upload_urls": ["https://..."],
"timing": "1"
})
// Power-user escape hatch — pass arbitrary fields not in the signature
generate_video({
"prompt": "Branded promo",
"extra_params": { "logo": "https://...", "logo_placement": "tr" }
})
Where downloaded videos go
Default: ~/Golpo/videos/. Filename pattern:
YYYYMMDD-HHMMSS_<title-slug>_<video-id-short>.mp4
Override per call with output_dir, or globally with GOLPO_VIDEO_DIR env
var. Pass no_download=True to skip.
Visual styles cheat sheet
Golpo Sketch (use_lineart_2_style):
| Value | Style |
|---|---|
false |
Classic (default) |
true |
Improved (BETA) |
advanced |
Formal |
whiteboard |
Dry Erase |
modern_minimal |
Professional Clean |
storytelling |
Crayon |
Golpo Canvas (use_2_0_style: true, image_style):
| Value | Style |
|---|---|
chalkboard_white |
Chalkboard (B/W, default) |
neon |
Chalkboard Color |
whiteboard |
Whiteboard |
modern_minimal |
Modern Minimal |
playful |
Playful |
technical |
Technical |
editorial |
Editorial |
marker |
Sharpie |
Canvas-only pen cursors: pen_style = none | stylus | marker | pen.
Sketch and Canvas are mutually exclusive — pick one engine per video.
Voices, languages, music
- Voices (
style):solo-female-3(default),solo-female-4,solo-male-3,solo-male-4. - Languages (
language): 44+ codes —en,hi,es,fr,de,pt,ja,zh,ar,bn,ta,ur, … - Background music (
bg_music):jazz,lofi,whimsical,dramatic,engaging,hyper,inspirational,documentary.
Canvas additionally supports display_language for separating narration
language from on-screen text language.
Architecture
src/golpo_mcp/
├── __init__.py # __version__
├── __main__.py # entry point (`golpo-mcp` console script)
├── server.py # FastMCP instance + @mcp.tool() decorators
├── client.py # Golpo HTTP client (pure functions, no MCP)
├── auth.py # API key resolution
└── downloads.py # MP4 streaming + filename slug logic
The package is layered:
client.pyis a usable Golpo Python client on its own —import golpo_mcp.clientand call functions directly without MCP.server.pyis a thin MCP wrapper aroundclient.py.- Adding a new tool: drop a
@mcp.tool()function intoserver.py. Type annotations become JSON Schema automatically.
Extending: adding new tools
# in server.py
@mcp.tool()
def my_new_tool(arg1: str, arg2: int = 42) -> dict:
"""Docstring becomes the tool description seen by the LLM."""
try:
return {"ok": True, "echoed": arg1, "n": arg2}
except Exception as e:
return _error(e)
That's it — the server picks it up at import time. Add a row to the tool catalog table in this README and ship.
Pricing
Golpo API: $1 = 1 credit, 2 credits per minute of generated video. Minimum $200 entry on the API tier. Billing happens server-side; check usage at video.golpoai.com.
Related
- Golpo Claude Code skill — the Claude-Code-specific packaging (uses the same auth file).
- Golpo Video API docs — https://video.golpoai.com/api-docs/endpoints/v1
- Payload examples — https://video.golpoai.com/guide/golpo-ai-video-api-payload-examples
- MCP spec — https://modelcontextprotocol.io
License
MIT.
Metadata
Release files for golpo-mcp 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| golpo_mcp-0.1.1.tar.gz | 20.8 kB | Without provenance | Details for golpo_mcp-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| golpo_mcp-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for golpo_mcp-0.1.1-py3-none-any.whl |
Total release size: 36.3 kB
Release files / golpo_mcp-0.1.1.tar.gz
| Download URL | golpo_mcp-0.1.1.tar.gz |
|---|---|
| Size | 20.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8cb542d54eb150e41d1d6980c03a7466413503f10b0c07eac23e5f7851ab12fe
|
|
BLAKE2b-256 checksum How to use checksums |
63e68296964ed2b7c828c36571e8330a06f5393ec8aac7526c1ccab419f9d08a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.9
|
Release files / golpo_mcp-0.1.1-py3-none-any.whl
| Download URL | golpo_mcp-0.1.1-py3-none-any.whl |
|---|---|
| Size | 15.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
90ec6779db540bda931f031b8e163c2b69865ce2535461ab6291e525b1c965d2
|
|
BLAKE2b-256 checksum How to use checksums |
2a19caf4f8743622052215e24fca1b6e2b1833573739ee792d3b5b7d0b10456e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.9
|
Security for golpo-mcp 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.