# FrameThrower [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/framethrower-ai/framethrower-mcp  
**GitHub Stars:** 1  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/framethrower

## Description
Film stills from 5,489 films, searchable by lighting, lens character, shot size, colour and mood.

## Tools
Capabilities this server exposes over MCP:

- **search_frames** — Search the FrameThrower cinematography reference library by concept, mood, color, composition, or scene. Returns reference frames with film/credits metadata, a preview thumbnail, the full-resolution image URL (use this one for slide decks and documents), a precomputed DEPTH MAP url (greyscale, same dimensions as the frame — pass it straight to a depth ControlNet or any image-to-image pipeline that wants geometry), and a link to view on FrameThrower.
- **find_by_craft** — Find frames by specific cinematography craft attributes — lens character, shot size, visual style, setting, time of day, director, or year range. All optional; combine to narrow. Use this to refine a search precisely.
- **find_similar** — Find frames visually/semantically similar to a given frame id (from a prior result). Use this to pull more references like one the user shortlisted.
- **get_frame_details** — Get the full metadata + preview thumbnail + full-resolution image URL + depth map URL + link for a single frame id. The depth map is precomputed and free — use it when the user is generating images and needs the composition or camera geometry of this frame.

## Claude Desktop Quick Installation
Remote MCP endpoint (confidence: high). Install path detected from listing signals. Add as a URL/SSE server in your client:

```json
"mcpServers": {
  "framethrower": {
    "url": "https://framethrower.ai/api/mcp"
  }
}
```

## Documentation

## What the FrameThrower MCP server does

FrameThrower MCP server exposes a film-still reference library through a remote MCP endpoint. The library contains frames from 5,489 films, indexed by visual properties such as lighting, lens character, shot size, colour, and mood. Search results identify the film, director, and cinematographer, and include a thumbnail URL, colour palettes, metadata, and a link back to FrameThrower.

The service is intended for discovery and visual study rather than image delivery. It returns references and links, not raw image bytes. The frames are shown at reduced resolution, and rights remain with their respective owners.

## How it works

Connect an MCP-compatible client to `https://framethrower.ai/api/mcp` and complete the OAuth 2.1 sign-in flow. After connecting, the server supplies usage instructions that guide the agent through an iterative reference workflow:

1. Search for a visual idea.
2. Present a small selection with film information and links.
3. Refine the selection using feedback such as “more like this,” “colder,” or “tighter.”
4. Repeat until the desired reference is found.

The FrameThrower MCP server keeps a link with each result because chat clients may not reliably render inline images, while the FrameThrower gallery provides the full reference context.

## Setup and configuration

No local installation or long-running process is required for clients that support the remote MCP URL. In Claude, add a custom connector and paste the endpoint, then sign in when prompted. In Cursor, add the endpoint to `~/.cursor/mcp.json` or use the provided installation link.

Clients that only support stdio can connect through `mcp-remote`. The bridge runs with `npx` and forwards requests to the hosted endpoint while handling OAuth. The repository contains per-client setup instructions, tool signatures, manifests, and examples; it does not contain a server that you run locally.

There is no API key to configure. Authentication uses the signed-in FrameThrower account. New accounts receive $2 in credits without entering a card. After that, credits cost $1 per 1,000, and each tool call uses 2 credits. Credits do not expire, and the service has no rate limits.

## Tools and capabilities

The FrameThrower MCP server provides four tools:

- `search_frames` accepts a required natural-language query and an optional result limit from 1 to 40. It suits concepts such as a neon-lit rainy street at night.
- `find_by_craft` filters by lens, shot size, visual style, setting, time of day, director, and year range. All filters are optional and can be combined.
- `find_similar` takes a frame ID from an earlier result and returns related frames for refinement.
- `get_frame_details` takes a frame ID and returns detailed information for that frame.

Each tool call costs 2 credits. Results include metadata, thumbnails, colour palettes, and deep links, but not image data. The same account can also be used with the service’s REST API and npm SDK, although those are separate interfaces from MCP.

## Limitations and notes

This is a hosted service, so it cannot be self-hosted from the repository. The repository acts as a connector and documentation package. A client that only supports stdio needs the `mcp-remote` bridge.

Use the results as cinematography references for commentary, education, and study. They are not a licensing or image-download pipeline. Running out of credits produces a response containing the remaining balance and top-up location rather than failing silently.

_Full upstream README: https://allmcps.com/mcp/framethrower/readme_