Framethrower MCP Server

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

search_frames

find_by_craft

All optional — combine them to narrow.

find_similar

get_frame_details

---

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.