{
  "markdown": "# FrameThrower MCP Server\n\n**Film references, inside your agent.** Connect any MCP client to a\ncinematography reference library of **5,489 films**, indexed frame by frame on\nlighting, lens character, shot size, colour and mood.\n\nAsk for a look in conversation and the agent comes back with real frames,\ncredited to their film, director and cinematographer.\n\n```\nhttps://framethrower.ai/api/mcp\n```\n\nRemote server, OAuth 2.1, **four tools**, **no rate limits**, **$2 of credits\nfree on signup** (no card).\n\n---\n\n## Quick start\n\n### Claude (Desktop / Web)\n\nSettings → **Connectors** → **Add custom connector** → paste:\n\n```\nhttps://framethrower.ai/api/mcp\n```\n\nSign in when the browser opens. That's it.\n\n### Cursor\n\nOne-click:\n\n[![Add to Cursor](https://img.shields.io/badge/Add%20to-Cursor-black)](cursor://anysphere.cursor-deeplink/mcp/install?name=framethrower&config=eyJ1cmwiOiJodHRwczovL2ZyYW1ldGhyb3dlci5haS9hcGkvbWNwIn0=)\n\nOr add to `~/.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"framethrower\": {\n      \"url\": \"https://framethrower.ai/api/mcp\"\n    }\n  }\n}\n```\n\n### Clients that only speak stdio\n\nBridge with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote), which\nhandles the OAuth flow for you:\n\n```json\n{\n  \"mcpServers\": {\n    \"framethrower\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-remote\", \"https://framethrower.ai/api/mcp\"]\n    }\n  }\n}\n```\n\nFull per-client steps in [docs/install.md](docs/install.md).\n\n---\n\n## The four tools\n\n| Tool | Credits | What it does |\n|------|---------|--------------|\n| `search_frames` | 2 | Search by concept, mood, colour, composition or scene, in natural language |\n| `find_by_craft` | 2 | Find frames by cinematography attribute — lens, shot size, style, setting, time of day, director, year |\n| `find_similar` | 2 | More frames like one already shortlisted. This is the refinement loop |\n| `get_frame_details` | 2 | Full metadata, thumbnail and link for a single frame |\n\n### `search_frames`\n\n| Argument | Type | Notes |\n|---|---|---|\n| `query` | string, **required** | e.g. `\"neon-lit rainy street at night\"` |\n| `limit` | number, 1–40 | defaults to 12 |\n\n### `find_by_craft`\n\nAll optional — combine them to narrow.\n\n| Argument | Type | Notes |\n|---|---|---|\n| `lens` | string | `\"anamorphic\"`, `\"spherical\"`, `\"vintage_soft\"` |\n| `shot_size` | string | `\"closeup\"`, `\"wide\"`, `\"medium\"` |\n| `visual_style` | string | |\n| `setting` | string | `\"interior\"` or `\"exterior\"` |\n| `time_of_day` | string | `\"night\"`, `\"day\"` |\n| `director` | string | |\n| `year_min` / `year_max` | number | year range |\n| `limit` | number, 1–40 | defaults to 12 |\n\n### `find_similar`\n\n| Argument | Type | Notes |\n|---|---|---|\n| `frameId` | string, **required** | an id from a previous result |\n| `limit` | number, 1–40 | defaults to 12 |\n\n### `get_frame_details`\n\n| Argument | Type | Notes |\n|---|---|---|\n| `frameId` | string, **required** | |\n\n---\n\n## How it's meant to be used\n\nThe server sends usage instructions on connect, so a client doesn't need to be\ntold how to behave. The loop it asks for:\n\n1. **Search** — the agent calls `search_frames` with what you described.\n2. **Show a few** — about four, each with film, director and a link. Not a dump.\n3. **React** — \"more like #2\", \"colder\", \"tighter\". That becomes a\n   `find_similar` on that frame, or a `find_by_craft` with attributes adjusted.\n4. **Repeat** until it's right.\n\nEvery result keeps a link back to FrameThrower, because inline image rendering\nin chat is unreliable and the gallery is where the frames look like themselves.\n\nSee [examples/prompts.md](examples/prompts.md) for conversations that work.\n\n---\n\n## What it costs\n\n**$2 of credits free on signup, no card.** Then $1 = 1,000 credits, and each\ntool call costs 2 — so **$1 covers 500 calls**. Credits never expire. There are\n**no rate limits**.\n\nRun out and the tool replies with a message saying so, including your balance\nand where to top up, so the agent can explain itself rather than failing\nsilently.\n\n---\n\n## What it returns — and what it doesn't\n\nTools return metadata, a thumbnail URL, colour palettes and a deep link back to\nFrameThrower. **Never raw image bytes.**\n\nThis is a discovery and reference tool, not an image-delivery pipe. The frames\nare not ours to license — they are shown at reduced resolution as references for\ncommentary, education and study, and rights remain with their owners. See\n[intended use](https://framethrower.ai/legal/intended-use).\n\n---\n\n## Why there's no server code here\n\nThe FrameThrower MCP server is **remote and hosted** — you connect to it, you\ndon't run it. So this repo is the connector: manifests, per-client setup, tool\nsignatures and worked examples. Nothing to install, nothing to keep running,\nand no API key to manage — OAuth means the agent acts as your signed-in\nFrameThrower account.\n\n---\n\n## Also available\n\n- **REST API** — 11 endpoints, no rate limits.\n  [Machine-readable spec](https://framethrower.ai/api/v1) ·\n  [docs](https://framethrower.ai/developers)\n- **npm SDK** — `npm install framethrower-ai`\n  ([source](https://github.com/framethrower-ai/framethrower-sdk))\n\nSame account, same credits.\n\n---\n\n## About\n\nFrameThrower is the reference app for the future creative: one of the largest\nfilm still libraries on the internet, callable from a REST API, an MCP server\nand an npm SDK. Built by senior filmmakers and ads creatives, for working film\nprofessionals.\n\n[framethrower.ai](https://framethrower.ai) · [/mcp](https://framethrower.ai/mcp)\n\nMIT licensed.\n",
  "bytes": 5503,
  "sha": "de1be0f0ed35a87a6e5f2ff4748aac270ea9ab1b7d9d01ad8100ca45bdb303de",
  "repo_slug": "framethrower-ai/framethrower-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_ai_framethrower_framethrower_5f1b51ca/readme"
}