FrameThrower MCP Server
Film references, inside your agent. Connect any MCP client to acinematography reference library of 5,489 films, indexed frame by frame onlighting, lens character, shot size, colour and mood.
Ask for a look in conversation and the agent comes back with real frames,credited to their film, director and cinematographer.
https://framethrower.ai/api/mcp
Remote server, OAuth 2.1, four tools, no rate limits, $2 of creditsfree on signup (no card).
Quick start
Claude (Desktop / Web)
Settings → Connectors → Add custom connector → paste:
https://framethrower.ai/api/mcp
Sign in when the browser opens. That's it.
Cursor
One-click:
Or add to ~/.cursor/mcp.json:
{
"mcpServers": {
"framethrower": {
"url": "https://framethrower.ai/api/mcp"
}
}
}
Clients that only speak stdio
Bridge with mcp-remote, whichhandles the OAuth flow for you:
{
"mcpServers": {
"framethrower": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://framethrower.ai/api/mcp"]
}
}
}
Full per-client steps in docs/install.md.
The four tools
| Tool | Credits | What it does |
|---|---|---|
search_frames |
2 | Search by concept, mood, colour, composition or scene, in natural language |
find_by_craft |
2 | Find frames by cinematography attribute — lens, shot size, style, setting, time of day, director, year |
find_similar |
2 | More frames like one already shortlisted. This is the refinement loop |
get_frame_details |
2 | Full metadata, thumbnail and link for a single frame |
search_frames
| Argument | Type | Notes |
|---|---|---|
query |
string, required | e.g. "neon-lit rainy street at night" |
limit |
number, 1–40 | defaults to 12 |
find_by_craft
All optional — combine them to narrow.
| Argument | Type | Notes |
|---|---|---|
lens |
string | "anamorphic", "spherical", "vintage_soft" |
shot_size |
string | "closeup", "wide", "medium" |
visual_style |
string | |
setting |
string | "interior" or "exterior" |
time_of_day |
string | "night", "day" |
director |
string | |
year_min / year_max |
number | year range |
limit |
number, 1–40 | defaults to 12 |
find_similar
| Argument | Type | Notes |
|---|---|---|
frameId |
string, required | an id from a previous result |
limit |
number, 1–40 | defaults to 12 |
get_frame_details
| Argument | Type | Notes |
|---|---|---|
frameId |
string, required |
How it's meant to be used
The server sends usage instructions on connect, so a client doesn't need to betold how to behave. The loop it asks for:
- Search — the agent calls
search_frameswith what you described. - Show a few — about four, each with film, director and a link. Not a dump.
- React — "more like #2", "colder", "tighter". That becomes a
find_similaron that frame, or afind_by_craftwith attributes adjusted. - Repeat until it's right.
Every result keeps a link back to FrameThrower, because inline image renderingin chat is unreliable and the gallery is where the frames look like themselves.
See examples/prompts.md for conversations that work.
What it costs
$2 of credits free on signup, no card. Then $1 = 1,000 credits, and eachtool call costs 2 — so $1 covers 500 calls. Credits never expire. There areno rate limits.
Run out and the tool replies with a message saying so, including your balanceand where to top up, so the agent can explain itself rather than failingsilently.
What it returns — and what it doesn't
Tools return metadata, a thumbnail URL, colour palettes and a deep link back toFrameThrower. Never raw image bytes.
This is a discovery and reference tool, not an image-delivery pipe. The framesare not ours to license — they are shown at reduced resolution as references forcommentary, education and study, and rights remain with their owners. Seeintended use.
Why there's no server code here
The FrameThrower MCP server is remote and hosted — you connect to it, youdon't run it. So this repo is the connector: manifests, per-client setup, toolsignatures and worked examples. Nothing to install, nothing to keep running,and no API key to manage — OAuth means the agent acts as your signed-inFrameThrower account.
Also available
- REST API — 11 endpoints, no rate limits.Machine-readable spec ·docs
- npm SDK —
npm install framethrower-ai(source)
Same account, same credits.
About
FrameThrower is the reference app for the future creative: one of the largestfilm still libraries on the internet, callable from a REST API, an MCP serverand an npm SDK. Built by senior filmmakers and ads creatives, for working filmprofessionals.
MIT licensed.
