# MCP server

> A Model Context Protocol server so Claude, Cursor and other MCP clients can process video with FrameQuery. Coming with SDK 0.2.

Source: https://www.framequery.com/docs/mcp (updated 2026-10-13)

> **Not released yet.** The FrameQuery MCP server ships with the 0.2 SDKs as `npx @framequery/mcp`. The package is not on npm today, so the commands below will not work until it is. This page describes what is planned.

## What it will do

`@framequery/mcp` is a local (stdio) MCP server built on the TypeScript SDK. It lets an assistant such as Claude Desktop, Claude Code or Cursor process a video or audio file and read the results, using your own API key.

| Tool | What it does | Costs credits |
|---|---|---|
| `process_video` | Create a job from a URL or a local file (resumable upload) and wait briefly for it | Yes |
| `wait_for_job` | Wait for a job, with progress updates | No |
| `get_job` | Read a job's state and stages | No |
| `get_transcript` | Read a transcript as compact text, paged by time | No |
| `get_scenes` | Read scenes, paged, with selectable fields | No |
| `list_jobs` | List recent jobs | No |
| `get_balance` | Read your credit balance | No |
| `estimate_cost` | Price a job before running it | No |
| `cancel_job` | Cancel a running job | No |

Planned safety limits: local files only from directories you allow, a per-session spending cap, a maximum job duration, and a read-only mode that hides `process_video` and `cancel_job`. Tool retries reuse a deterministic idempotency key, so an assistant retrying a call does not pay twice.

## Planned configuration

The server will read `FRAMEQUERY_API_KEY` from its environment, like the SDKs. For Claude Desktop, Cursor and other clients that use an `mcpServers` block:

```json
{
  "mcpServers": {
    "framequery": {
      "command": "npx",
      "args": ["-y", "@framequery/mcp"],
      "env": { "FRAMEQUERY_API_KEY": "fq_live_..." }
    }
  }
}
```

Until it ships, any agent can use the API directly: start with the [Agent quickstart](https://www.framequery.com/docs/agent-quickstart), or point it at [/llms.txt](https://www.framequery.com/llms.txt) and the [OpenAPI document](https://api.framequery.com/v1/api/openapi.json).