# 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:

[![Add to Cursor](https://img.shields.io/badge/Add%20to-Cursor-black)](cursor://anysphere.cursor-deeplink/mcp/install?name=framethrower&config=eyJ1cmwiOiJodHRwczovL2ZyYW1ldGhyb3dlci5haS9hcGkvbWNwIn0=)

Or add to `~/.cursor/mcp.json`:

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

### Clients that only speak stdio

Bridge with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote), which
handles the OAuth flow for you:

```json
{
  "mcpServers": {
    "framethrower": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://framethrower.ai/api/mcp"]
    }
  }
}
```

Full per-client steps in [docs/install.md](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](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](https://framethrower.ai/legal/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](https://framethrower.ai/api/v1) ·
  [docs](https://framethrower.ai/developers)
- **npm SDK** — `npm install framethrower-ai`
  ([source](https://github.com/framethrower-ai/framethrower-sdk))

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](https://framethrower.ai) · [/mcp](https://framethrower.ai/mcp)

MIT licensed.