# Frankreel

> Frankreel is a YouTube growth app for creators: keyword research, title and thumbnail scoring, AI titles, descriptions, tags and video ideas, outlier videos, competitor tracking, a channel audit and an AI coach, built from the creator's own channel data. AI assistants can use it on a user's behalf through a remote MCP server or a REST API.

Connect an AI assistant: add the MCP server https://frankreel.com/api/mcp as a custom connector (OAuth sign-in, no key needed). Scripts and tools without OAuth use a personal API key from Settings, AI & API, sent as "Authorization: Bearer fr_live_...".
Pricing for agents: tools that use AI cost exactly 1 credit from the user's monthly allowance and are not charged if they fail. All other tools are free. Every response reports the credits remaining.

## Connect
- [AI & developer guide](https://frankreel.com/developers): setup for Claude, ChatGPT, Cursor, VS Code, Gemini CLI and curl
- [MCP server](https://frankreel.com/api/mcp): Streamable HTTP, stateless, OAuth 2.1 or API key
- [OpenAPI 3.1 spec](https://frankreel.com/api/v1/openapi.json): REST API, usable as a ChatGPT GPT Action or Gemini extension
- [Full reference for LLMs](https://frankreel.com/llms-full.txt): every tool, parameters, costs and errors

## Product
- [Home and pricing](https://frankreel.com/): plans, credits and the 14-day refund rule
- [Help](https://frankreel.com/help)
- [Changelog](https://frankreel.com/changelog)
- [Privacy](https://frankreel.com/privacy)
- [Terms](https://frankreel.com/terms)

---

# Frankreel for AI assistants: full reference

## How it works
- One account, one active YouTube channel. Every tool acts on the signed-in user's own data and active channel; other users' data is never reachable.
- Authentication: OAuth 2.1 with PKCE (authorization server metadata at https://frankreel.com/.well-known/oauth-authorization-server, protected resource metadata at https://frankreel.com/.well-known/oauth-protected-resource/api/mcp, dynamic client registration and client ID metadata documents supported), or a personal API key (fr_live_...). Scopes: read, write.
- Credits: AI tools cost 1 AI credit (ask_coach costs 1 coach message instead). Limits per month: Free 30 AI credits and 10 coach messages, Creator 300 and 100, Studio 1,000 and 250. A failed call is never charged. Every success includes "credits": {"charged": {...}, "remaining": {...}}.
- Nothing changes on YouTube unless publish_draft is called with confirm=true. Only do that when the user asks.
- Rate limit: 60 requests a minute per API key or connected app.
- REST responses: success {"result": ..., "credits": ...}; error {"error": {"code", "message"}} with the HTTP status.

## Tools
### get_account
Account, plan and credits. Who you are signed in as, your plan, the YouTube channels you have linked (the active one is used by every other tool), and how many AI credits and coach messages you have left this month. Free: uses no credits.
- REST: GET https://frankreel.com/api/v1/me
- Scope: read. Read-only.
- Parameters: none

### get_channel_overview
Channel stats and insights. Stats for your connected YouTube channel (subscribers, views over the last 28 days, video count, with changes) plus the current insight cards: breakout videos, weak titles, upload gaps. Free: uses no credits.
- REST: GET https://frankreel.com/api/v1/channel
- Scope: read. Read-only.
- Parameters: none

### channel_audit
Channel audit. A review of your channel's last 30, 60 or 90 days: subscriber and view change, upload rhythm, best and weakest videos, Shorts against long videos, and an SEO checklist over your last 20 uploads. Rule-based from public numbers. Needs the Creator or Studio plan. Free: uses no credits.
- REST: GET https://frankreel.com/api/v1/channel/audit
- Scope: read. Read-only.
- Parameters: 
  - days? (integer): Period to review: 30, 60 or 90 days.

### list_videos
List my videos. Videos on your connected channel, newest first, with views, views per hour and outlier score (how many times the channel's usual views a video got). Use the id with analyze_video, generate_titles and the other video tools. Free: uses no credits.
- REST: GET https://frankreel.com/api/v1/videos
- Scope: read. Read-only.
- Parameters: 
  - type? (long|short): long = regular videos, short = Shorts.
  - limit? (integer): How many, newest first (max 200).

### analyze_video
Analyze one of my videos. Full detail for one video on your channel: stats, title score with reasons, the SEO checklist (description length, keyword placement, tags, chapters), and the current draft if you are editing it in Frankreel. Free: uses no credits.
- REST: GET https://frankreel.com/api/v1/videos/{video_id}
- Scope: read. Read-only.
- Parameters: 
  - video_id (string): The video: Frankreel video id (from list_videos) or the YouTube video id (the v= part of the URL).

### generate_titles
AI title ideas for a video. Three new, honest title options for one of your videos, each with its title score, written for your channel profile (niche, tone, language, avoid list). Does not change anything on YouTube. Cost: 1 AI credit from your monthly allowance. If the call fails it is not charged.
- REST: POST https://frankreel.com/api/v1/videos/{video_id}/titles
- Scope: write. Changes data.
- Parameters: 
  - video_id (string): The video: Frankreel video id (from list_videos) or the YouTube video id (the v= part of the URL).
  - tone? (neutral|energetic|calm): Defaults to the tone in your channel profile.
  - length? (shorter|longer)
  - instruction? (string): Extra direction, e.g. "mention the price".

### generate_descriptions
AI descriptions for a video. Three description drafts (300-900 characters) for one of your videos, with the keyword and payoff in the first two lines. Does not change anything on YouTube. Cost: 1 AI credit from your monthly allowance. If the call fails it is not charged.
- REST: POST https://frankreel.com/api/v1/videos/{video_id}/descriptions
- Scope: write. Changes data.
- Parameters: 
  - video_id (string): The video: Frankreel video id (from list_videos) or the YouTube video id (the v= part of the URL).

### suggest_tags
AI tag ideas for a video. Up to 10 tags viewers actually search for, that the video does not have yet. Cost: 1 AI credit from your monthly allowance. If the call fails it is not charged. (Tag ideas inside the Frankreel editor stay free.)
- REST: POST https://frankreel.com/api/v1/videos/{video_id}/tags
- Scope: write. Changes data.
- Parameters: 
  - video_id (string): The video: Frankreel video id (from list_videos) or the YouTube video id (the v= part of the URL).

### save_draft
Save a draft title, description or tags. Saves changes to the Frankreel draft for a video (title, description and/or tags). Nothing changes on YouTube until publish_draft is called. Free: uses no credits.
- REST: PATCH https://frankreel.com/api/v1/videos/{video_id}/draft
- Scope: write. Changes data.
- Parameters: 
  - video_id (string): The video: Frankreel video id (from list_videos) or the YouTube video id (the v= part of the URL).
  - title? (string)
  - description? (string)
  - tags? (array)

### publish_draft
Publish a draft to YouTube. Publishes the saved draft's title, description and tags to the live video on YouTube. This changes the public video, so only call it when the user has explicitly asked to publish. The change is recorded in History and can be undone in Frankreel. Needs publishing access to the channel (granted once in the web app). Free: uses no credits.
- REST: POST https://frankreel.com/api/v1/videos/{video_id}/publish
- Scope: write. Changes data; destructive.
- Parameters: 
  - video_id (string): The video: Frankreel video id (from list_videos) or the YouTube video id (the v= part of the URL).
  - confirm (boolean): Must be true. Confirms the user asked to change the live video on YouTube.

### list_changes
Published changes and their results. Every title, description and tag change published through Frankreel, with before and after, and how views per day moved afterwards (measured from 3 days after the change). Free: uses no credits.
- REST: GET https://frankreel.com/api/v1/changes
- Scope: read. Read-only.
- Parameters: none

### keyword_research
Keyword score. Scores a YouTube search term 0-100 from public YouTube data: demand (views going to the top results), competition (big channels and exact-match titles in the top results), and an overall score with the formula shown. Also returns related searches, longer matching searches and questions when Frankreel already knows them; if related is empty, call expand_keyword. Free plan shows the top 4 of each list. Free: uses no credits.
- REST: GET https://frankreel.com/api/v1/keywords
- Scope: read. Read-only.
- Parameters: 
  - q (string): The search term, e.g. "home workout".

### expand_keyword
Related keyword ideas (AI). Finds related searches, longer searches containing the term, and questions viewers ask about it. Each can then be scored with keyword_research. Cost: 1 AI credit from your monthly allowance when the AI runs; if Frankreel already has the related terms they are returned at no cost. If the call fails it is not charged.
- REST: POST https://frankreel.com/api/v1/keywords/expand
- Scope: write. Changes data.
- Parameters: 
  - q (string): The seed search term.

### score_title
Score a title. Scores a YouTube title 0-100 with the reasons (length, numbers, curiosity words, keyword position, capitals, punctuation). Deterministic: the same title always gets the same score. Free: uses no credits.
- REST: POST https://frankreel.com/api/v1/titles/score
- Scope: read. Read-only.
- Parameters: 
  - title (string)
  - keyword? (string): Main keyword; checks it appears early.

### score_thumbnail
Score a thumbnail. Scores a thumbnail 0-100 with checks for size, 16:9 shape, brightness, contrast, colour, clutter and the corner under the length badge. Rule-based and deterministic. Free: uses no credits.
- REST: POST https://frankreel.com/api/v1/thumbnails/score
- Scope: read. Read-only.
- Parameters: 
  - video_id? (string): Score the current thumbnail of one of your videos.
  - image_base64? (string): Or a JPG or PNG under 2 MB, base64 encoded.

### find_outliers
Find outlier videos. Videos that got several times their channel's usual views, for a topic, ranked by outlier score. Good for spotting ideas that work. On the Free plan only type and period filters apply. Free: uses no credits.
- REST: GET https://frankreel.com/api/v1/outliers
- Scope: read. Read-only.
- Parameters: 
  - q? (string): Topic to search, e.g. "kettlebell". Empty = videos Frankreel already tracks.
  - type? (long|short)
  - period? (week|month|3m|6m|year|all)
  - min_score? (number): Minimum outlier score (paid plans).
  - min_views? (integer): Paid plans.
  - max_subscribers? (integer): Only channels up to this size (paid plans).
  - min_views_per_hour? (number): Paid plans.
  - max_length_minutes? (integer): Paid plans.

### list_competitors
Tracked competitors. Channels you track as competitors, with their size and usual views per video. Free: uses no credits.
- REST: GET https://frankreel.com/api/v1/competitors
- Scope: read. Read-only.
- Parameters: none

### competitor_videos
Competitor uploads. Recent uploads from the channels you track, sorted by views, views per hour or date. Free: uses no credits.
- REST: GET https://frankreel.com/api/v1/competitors/videos
- Scope: read. Read-only.
- Parameters: 
  - sort? (views|vph|date): vph = views per hour.
  - period? (48h|week|month|all)
  - include_mine?

### search_channels
Find a YouTube channel. Looks up YouTube channels by @handle, channel URL or name, to add as competitors. Free: uses no credits.
- REST: GET https://frankreel.com/api/v1/channels/search
- Scope: read. Read-only.
- Parameters: 
  - q (string): @handle, channel URL or a name.

### add_competitor
Track a competitor. Starts tracking a channel as a competitor (Free plan: 3, Creator: 20, Studio: 50). Free: uses no credits.
- REST: POST https://frankreel.com/api/v1/competitors
- Scope: write. Changes data.
- Parameters: 
  - channel_id (string): Frankreel channel id from search_channels.

### remove_competitor
Stop tracking a competitor. Stops tracking a competitor channel. Free: uses no credits.
- REST: DELETE https://frankreel.com/api/v1/competitors/{channel_id}
- Scope: write. Changes data; destructive.
- Parameters: 
  - channel_id (string)

### list_ideas
My video ideas. Video ideas Frankreel has made for your channel (daily ideas and topic searches), newest first, with the predicted views relative to your usual. Free: uses no credits.
- REST: GET https://frankreel.com/api/v1/ideas
- Scope: read. Read-only.
- Parameters: 
  - status? (new|saved|dismissed|all)
  - limit? (integer)

### generate_ideas
AI video ideas for a topic. Video ideas about a topic, fitted to your channel, its best videos and competitor breakouts (Free plan: 3 ideas, paid: 10). Cost: 1 AI credit from your monthly allowance, and counts as one of your monthly topic searches (Free: 3). If the call fails it is not charged.
- REST: POST https://frankreel.com/api/v1/ideas
- Scope: write. Changes data.
- Parameters: 
  - topic (string): Topic or keyword to get ideas about.

### create_blueprint
Video blueprint for an idea. Turns an idea into a plan you can film: three titles, a hook for the first 15 seconds, a beat-by-beat outline and thumbnail concepts. Made once per idea; asking again returns the same blueprint at no cost. Cost: 1 AI credit from your monthly allowance the first time. If the call fails it is not charged.
- REST: POST https://frankreel.com/api/v1/ideas/{idea_id}/blueprint
- Scope: write. Changes data.
- Parameters: 
  - idea_id (string): Idea id from list_ideas or generate_ideas.

### ask_coach
Ask the AI coach. Asks Frankreel's YouTube coach a question about your channel. Answers are grounded in your channel's numbers, competitors and saved keywords. The conversation is saved in the Coach page. Cost: 1 coach message from your monthly allowance (Free: 10, Creator: 100, Studio: 250); no AI credits are used. If the call fails it is not charged.
- REST: POST https://frankreel.com/api/v1/coach
- Scope: write. Changes data.
- Parameters: 
  - message (string)
  - thread_id? (string): Continue an earlier conversation.
  - mode? (fast|deep): deep = slower, more thorough answer.

## Errors
- invalid_input (400): A parameter is missing or not valid. The message says which.
- unauthorized / invalid_token (401): No key, or the key or token is wrong, revoked or expired.
- plan_limit (402): Monthly allowance used up (or feature needs a paid plan). Nothing was charged.
- insufficient_scope (403): A read-only key tried to act. Use a key with "Read and act" access.
- needs_write_scope (403): Publishing needs YouTube publishing access, granted once in the web app.
- not_found (404): No such video, idea or channel on your account.
- no_channel (409): Connect a YouTube channel in Frankreel first.
- rate_limited (429): 60 requests a minute per key. Wait for Retry-After seconds.
- youtube_quota / upstream_failed (503): YouTube or the AI service is unavailable (503 or 502). Nothing was charged; try again.

## Setup guides
### Claude (claude.ai, desktop and mobile)
Add Frankreel as a custom connector. You sign in to Frankreel and approve it; no key needed.
1. Open Customize, then Connectors (Team and Enterprise: an owner adds it under Organization settings, Connectors).
2. Choose Add custom connector.
3. Name it Frankreel and paste the server URL: https://frankreel.com/api/mcp
4. Click Add, then Connect. Sign in to Frankreel and press Allow.
5. In a chat, turn Frankreel on from the + menu, Connectors.

Server URL:
```
https://frankreel.com/api/mcp
```

### Claude Code
One command. Claude Code opens the browser to sign in the first time you use it.
1. Run the command, then type /mcp in Claude Code and choose Frankreel to sign in.

Terminal:
```
claude mcp add --transport http frankreel https://frankreel.com/api/mcp
```

### ChatGPT (apps and connectors)
Plans with developer mode can add Frankreel as an app over MCP, with OAuth sign-in.
1. Settings, Apps & Connectors, Advanced settings: turn on Developer mode (a workspace admin may need to allow it).
2. Back in Apps & Connectors, choose Create.
3. Name: Frankreel. MCP server URL: https://frankreel.com/api/mcp. Authentication: OAuth.
4. Create, sign in to Frankreel and press Allow.
5. In a chat, pick Frankreel from the + menu.

MCP server URL:
```
https://frankreel.com/api/mcp
```

### ChatGPT custom GPT (Actions)
For a custom GPT, import the OpenAPI spec and use an API key.
1. Create an API key in Frankreel: Settings, AI & API.
2. In the GPT editor: Configure, Create new action, Import from URL.
3. Paste: https://frankreel.com/api/v1/openapi.json
4. Authentication: API Key, Auth Type: Bearer, and paste your fr_live_ key.

OpenAPI URL:
```
https://frankreel.com/api/v1/openapi.json
```

### Cursor
Add to ~/.cursor/mcp.json (or .cursor/mcp.json in a project). Cursor signs you in with OAuth.
1. Save the file, then open Cursor Settings, MCP, and choose Login next to Frankreel.

mcp.json:
```
{
  "mcpServers": {
    "frankreel": {
      "url": "https://frankreel.com/api/mcp"
    }
  }
}
```

### VS Code (GitHub Copilot)
Add to .vscode/mcp.json, or run "MCP: Add Server" and choose HTTP.
1. Save the file and press Start above the server. VS Code asks you to sign in to Frankreel.

.vscode/mcp.json:
```
{
  "servers": {
    "frankreel": {
      "type": "http",
      "url": "https://frankreel.com/api/mcp"
    }
  }
}
```

### Gemini CLI
Add to ~/.gemini/settings.json. Uses an API key in a header.
1. Create an API key in Frankreel: Settings, AI & API.
2. Add the block below, then run /mcp in Gemini CLI to check the tools loaded.

~/.gemini/settings.json:
```
{
  "mcpServers": {
    "frankreel": {
      "httpUrl": "https://frankreel.com/api/mcp",
      "headers": {
        "Authorization": "Bearer fr_live_YOUR_KEY"
      }
    }
  }
}
```

### Other MCP clients and agents (n8n, Windsurf, Zed, Perplexity, your own)
Any client that supports remote MCP over Streamable HTTP works.
1. Server URL: https://frankreel.com/api/mcp
2. If the client supports OAuth sign-in, use it: discovery is automatic.
3. Otherwise send an API key: Authorization: Bearer fr_live_YOUR_KEY.
4. n8n: MCP Client Tool node, transport HTTP Streamable, Bearer auth with your key.

Server URL:
```
https://frankreel.com/api/mcp
```

## curl
Your account, plan and credits left:
```
curl https://frankreel.com/api/v1/me \
  -H "Authorization: Bearer $FRANKREEL_KEY"
```

Score a keyword (free):
```
curl "https://frankreel.com/api/v1/keywords?q=home%20workout" \
  -H "Authorization: Bearer $FRANKREEL_KEY"
```

Score a title (free):
```
curl https://frankreel.com/api/v1/titles/score \
  -H "Authorization: Bearer $FRANKREEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "I Tried Home Workouts for 30 Days", "keyword": "home workout"}'
```

AI title ideas for one of your videos (1 credit):
```
curl -X POST https://frankreel.com/api/v1/videos/VIDEO_ID/titles \
  -H "Authorization: Bearer $FRANKREEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tone": "calm"}'
```

MCP: list tools:
```
curl https://frankreel.com/api/mcp \
  -H "Authorization: Bearer $FRANKREEL_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```