FrameThrower

FrameThrower MCP Server

Film references, inside your agent. Connect any MCP client to a cinematography reference library of 5,489 films, indexed frame by frame on lighting, 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 credits free 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, which handles 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 be told how to behave. The loop it asks for:

1. Search — the agent calls search_frames with what you described.
2. Show a few — about four, each with film, director and a link. Not a dump.
3. React — "more like #2", "colder", "tighter". That becomes a find_similar on that frame, or a find_by_craft with attributes adjusted.
4. Repeat until it's right.

Every result keeps a link back to FrameThrower, because inline image rendering in 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 each tool call costs 2 — so $1 covers 500 calls. Credits never expire. There are no rate limits.

Run out and the tool replies with a message saying so, including your balance and where to top up, so the agent can explain itself rather than failing silently.

---

What it returns — and what it doesn't

Tools return metadata, a thumbnail URL, colour palettes and a deep link back to FrameThrower. Never raw image bytes.

This is a discovery and reference tool, not an image-delivery pipe. The frames are not ours to license — they are shown at reduced resolution as references for commentary, education and study, and rights remain with their owners. See intended use.

---

Why there's no server code here

The FrameThrower MCP server is remote and hosted — you connect to it, you don't run it. So this repo is the connector: manifests, per-client setup, tool signatures and worked examples. Nothing to install, nothing to keep running, and no API key to manage — OAuth means the agent acts as your signed-in FrameThrower 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 largest film still libraries on the internet, callable from a REST API, an MCP server and an npm SDK. Built by senior filmmakers and ads creatives, for working film professionals.

framethrower.ai · /mcp

MIT licensed.