FrameThrower MCP server

Introduction

The FrameThrower MCP server gives any MCP client search access 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.

The same connector reaches the commercials library: whole spots and the shots inside them, with credits for every role, awards, story and script. Ask what a brand or a director has made, which spots won at Cannes, or for shots of a particular moment, and the agent answers from the library with stills and a link to watch each spot.

Server URL

https://framethrower.ai/api/mcp

OAuth 2.1 · films and commercials · no rate limits · setup instructions per client

Connect it

claude mcp add --transport http framethrower https://framethrower.ai/api/mcp

Clients this is set up and documented for:

How an agent uses it

The server sends usage instructions on connect, so a client does not have to be told how to behave. The shape it asks for is: search, show a small set — about four — with film, director and a link each, then refine on what the user reacts to. Someone saying “more like #2, colder” becomes a find_similar call on that frame, or a find_by_craft with the attributes adjusted.

Every result carries a link back to FrameThrower, because inline image rendering in chat is unreliable and the gallery is where the frames actually look like themselves.

Pricing

The MCP server is included in the free plan. A new account gets 200 free credits, no card, and can connect and start calling tools straight away — there is no plan to upgrade to for access. Usage is metered per call, and you buy more credits when you want more calls.

There are no rate limits.

search_frames

Search the library by concept, mood, colour, composition or scene, in natural language.

find_by_craft

Find frames by specific cinematography attributes. All optional — combine them to narrow. At least one is required, or the tool asks for one rather than returning the whole library.

find_similar

Pull more frames like one the user already shortlisted. This is the refinement loop, and the tool the “more like that one” reply should reach for.

get_frame_details

Full metadata, thumbnail, depth map and link for a single frame.

Commercials tools

Things to ask once it is connected:

How it is wired: the agent talks to the one server URL above. Every commercials tool runs the same code as the REST endpoints, over two indexes — one entry per commercial (credits, awards, story; refreshed whenever the library updates) and one per shot (caption and tags). Each call is charged like a film search. Results carry stills, the facts and a watch link; shot clips come on request (8 credits for that call instead of 2), and the full-spot video is never sent.

The same connector reaches the commercials library: award-winning and everyday spots with credits for every role, awards, story, script and every shot tagged. Whole spots and the shots inside them; stills come back as URLs (shot clips too, when asked for), and every result links to watch the spot on FrameThrower. The same calls are in the REST API under /api/v1/commercials.

One place for the whole treatment: next to the commercials, the agent has the film library (the four tools above), and on FrameThrower there is the animation library, the moodboard / lookbook builder and the canvas — so commercial, film and animation references sit side by side and the whole treatment comes together in one place.

search_commercials

Whole commercials by idea or story, and/or by facts — brand, director, agency, production company, DP, editor, award show and level, year, industry, market, tone, season. Without a query it lists matches, award winners first.

search_commercial_shots

Single shots inside commercials by what is in frame, with shot tags (size, angle, setting, light, mood, people, product or logo in frame) and any commercial filter. Each shot carries its still, the clip of that shot and a link to the exact moment.

get_commercial

One commercial in full: idea, logline, tagline, every credit by role, every award, craft numbers (cuts per minute, when the product and brand land), the script with timings and the shot list.

similar_commercials

Commercials like a given one, by story (idea, tropes, tone) or by look (their shots).

similar_commercial_shots

More shots that look like the ones the user picked — “more like #3”.

commercials_profile

The track record of a brand, director, agency, production company, DP, editor or composer: spots, years, who they work with, awards by show, best and most recent work.

commercials_stats

Count and rank: how many commercials match a filter, broken down by brand, any credit, industry, year, tone, award show… — “which agencies won most at Cannes for car ads since 2015”.

Animation tools

Built for an AI-first creator: the agent breaks a story into scenes, finds references per scene and per character, refines with more like a frame — or like any image it generated — finds which series and films fit the story, and opens a frame in its sequence. Things to ask once it is connected:

How it is wired: the same connector, the same code as the REST endpoints under /api/v1/animation. The library is animation only — animated series and films (mostly anime, plus Western animation) — and every frame of every title is indexed, each with a caption of what is in it plus look and colour fingerprints. Each frame comes back with a 640px still to look at, the full-size still, its frame id and a link. Clips come on request (8 credits for that call instead of 2; an image search stays 10).

search_animation_frames

Frames for a scene, a moment or a character look, described in plain words — “a girl on a rooftop at dusk watching the city lights”. At most 3 frames per title unless per_title says otherwise.

similar_animation_frames

More frames like ones the user already has — frame ids from earlier results, or any image: a generated frame on the canvas, an upload, a sketch. An image costs 10 credits.

find_animation_titles

Which series and films fit what the user is making: a story brief, a title it should be like, a look (an image or frame ids), and/or filters — signals combine. One card per franchise. Each title has studio, director, genres, themes, its look, a synopsis and a poster. An image costs 10 credits.

get_animation_title

One series or film in depth: synopsis, studio and key credits, main characters, genres, themes, its look, the trailer, titles with a similar look and a similar story, and sample frames spread across it.

get_animation_sequence

A frame in its sequence: the shots just before and after it in the same episode or film, in order — to see how a moment is built, or to lay a beat out across canvas panels. With clips, the continuous video that covers them.

What comes back

Every tool returns frames as text an agent can quote: the film with its year, director and cinematographer, the craft attributes behind the shot, a thumbnail URL, the full-resolution image URL, and a link to the frame on FrameThrower. Plus a link to the same search as a gallery, for when the reader wants to keep going by hand.

Each frame also carries a depth map — greyscale, the same dimensions as the frame, precomputed for all 410,000 of them. An agent building a shot can hand that straight to a depth ControlNet to keep a reference's composition and camera geometry while changing everything else. It costs no extra credits and needs no extra call; the line is simply there in the result.

REST API too

The MCP server is four tools over the same library a REST API of eleven endpoints reaches — and the REST side has the three the tools do not: image search, colour search and the film catalogue. Same account, same credits.

npm install framethrower-ai

Common questions

What is the FrameThrower MCP server?

An MCP (Model Context Protocol) server at https://framethrower.ai/api/mcp that gives an AI agent search access to a cinematography reference library of 5,489 films. Four film tools — search_frames, find_by_craft, find_similar and get_frame_details — and seven for the commercials library (search_commercials, search_commercial_shots, get_commercial, similar_commercials, similar_commercial_shots, commercials_profile, commercials_stats). Connect it in Claude, Cursor or any MCP client and the agent can find real film references mid-conversation.

How do I connect it?

Add https://framethrower.ai/api/mcp as a remote MCP server in your client's connector settings. Authentication is OAuth 2.1 — your client opens a FrameThrower sign-in, and after that the agent acts as you, with the same reference access your account has. Cursor supports a one-click install link.

What does it cost?

It is included in the free plan — there is no tier to upgrade to for access. A new account gets 200 free credits, no card. Every tool call costs 2 credits and $1 = 1,000 credits, so $1 covers 500 tool calls, and you buy more credits per use when you want more calls. Credits never expire and there are no rate limits. When a balance runs out the tool returns a message saying so rather than failing silently.

Does it return images?

No image bytes, ever. Tools return metadata, a thumbnail URL and a deep link back to FrameThrower. It is a discovery and reference tool, not an image-delivery pipe — the frames are not ours to license, and rights remain with their owners.

Is there a REST API too?

Yes — 11 endpoints with bearer-token auth and no rate limits, plus an npm SDK (npm install framethrower-ai). The machine-readable spec is at framethrower.ai/api/v1 and the docs are at framethrower.ai/developers. Same credits, same account.

More: setup per client · API docs · the stills database