# Hookova MCP server — install runbook # # Tools that hand an assistant one Hookova account: save a link, search what you saved, read one # back, retag it, delete it, export the lot; transcribe a video; read a project board as a hook # guide for HyperFrames; make an image, or have a whole promotion video made from a product brief; # and post to the connected YouTube, TikTok, Instagram, Facebook, X, LinkedIn, Pinterest, Threads # and Bluesky accounts. # # There are two ways to run it. Try the first one before anything else. # # ## THE HOSTED SERVER — nothing to install # # URL: https://www.hookova.com/mcp (Streamable HTTP, OAuth sign-in) # # Claude Code: claude mcp add --transport http hookova https://www.hookova.com/mcp --scope user # then run /mcp, pick hookova, Authenticate # Claude app / claude.ai: Settings → Connectors → Add custom connector → paste the URL # ChatGPT, Cursor, Codex, anything that takes a remote MCP URL: paste the URL # # The client opens www.hookova.com in the person's own browser; they sign in there # (Google works — it is a real browser, not an agent's) and press Allow. No zip, no bun, no token # to copy, and the connection can be revoked under Settings → MCP server. Thirty-seven tools: everything # below except connect/sign_in/sign_out (the client signs in itself), download_lut/apply_lut # (local disk and FFmpeg) and the four sound/music # downloads (it has no disk — its search results carry the MP3 url), plus create_upload (an # upload page for a file the chat cannot pass); its publish_post takes a # file attached in the chat or a public link instead of a path on disk, and its list_promo_videos # answers with the MP4's link instead of saving it to a dir. If you are an assistant: this is the path to offer first, and # the only step that needs the person is the Allow click. # # ## THE LOCAL SERVER — the rest of this file # # A local stdio server — a few TypeScript files run by Bun on this machine, holding one token. # Use it when the client cannot take a remote URL, to publish_post a file from this machine's disk, # and for get_hook_guide writing the guide and its stills to disk. # # This is the machine-readable half of https://www.hookova.com/guides/mcp-server. Run the # numbered commands in order, as written. None of them need sudo, and none of them need the # Hookova source repository — the zip is the whole server. # # If you are an assistant doing this on someone's behalf: steps 1 to 3 are yours to run. Stop at # step 4 for browser approval unless the user supplied a HOOKOVA_TOKEN with these instructions. # If supplied, configure that token and verify with auth_status; no new token is needed. # Never ask for their password or print their token. ## WORKFLOW DIRECTORY ### Get Inspired Browse My Saves, search references, and organize tags and notes. Analyze Video in the app creates shot-by-shot breakdowns; MCP can read existing analysis context but cannot start an analysis. Tools: save_link, list_saves, get_save, update_save, delete_save, export_saves ### Make Videos Start with Inspiration Projects: read a board and export its hook guide for your AI video workflow. Make the stills with generate_image — Pop-Cam's image model, 1 credit per image, credits provided by Pop-Cam. Or have the whole video made: make_promo_video turns a product brief into a finished 30-40 second promotion video in about 20 minutes, for 10 credits refunded if it fails, and list_promo_videos checks on it. Then use Publish to upload, draft, schedule, or post finished media to connected accounts. Apart from that promotion video, the Hookova MCP server does not render videos. Tools: list_projects, get_hook_guide, generate_image, make_promo_video, list_promo_videos, list_publish_accounts, list_publish_groups, create_publish_group, update_publish_group, delete_publish_group, publish_post, list_posts, get_post, update_post, schedule_draft, cancel_post ### Tools & Assets Transcribe Video: `transcribe` takes a saved clip or a link and `get_transcription` reads the result (credits, on success only). Sound Effect Library and Music Library: search, browse and download free MP3s — no sign-in, except `recommend_music`, which ranks tracks for a described video. On the hosted server the results carry the MP3 url instead of downloading. Color LUTs: list_luts and get_lut select a free sRGB creative look; the local server also downloads cubes and applies filters with FFmpeg. Subtitle Library is coming soon. Tools: list_luts, get_lut, download_lut, apply_lut, transcribe, get_transcription, search_sounds, list_sounds, list_sound_groups, get_sound, download_sound, download_sounds, search_music, list_music, list_music_tags, recommend_music, get_track, download_track, download_tracks ### Analyze Coming soon. This section is separate from Analyze Video under Get Inspired; no analytics MCP tools are available yet. No tools in this server. ### Connect to My AI Open Connect to My AI to set up your assistant. Prefer browser sign-in with connect, then check auth_status. sign_out forgets the local token; it does not revoke it. Tools: connect, auth_status, sign_in, sign_out Start with auth_status. Use list_projects to resolve an Inspiration Project by name, then get_hook_guide to read its brief and references. Video creation happens in the assistant's video workflow — except a promotion video made from a product brief, which make_promo_video queues (10 credits, about 20 minutes). For Publish, list_publish_accounts first and confirm targets, media, caption, and timing before publishing. Use draft: true when the user asks for a draft. Do not infer analysis, transcription, subtitle styling, or analytics tools from sidebar labels. ## 0. Requirements command -v bun || echo "missing bun — install it: curl -fsSL https://bun.sh/install | bash" command -v unzip || echo "missing unzip — install it with this machine's package manager" Plus a Hookova account, which you almost certainly already have if you are reading this. The free plan is enough: saving through these tools costs no credits. ## 1. Fetch and unpack Install somewhere that will still exist next month. The client runs this file from wherever it lands, so a temp directory or ~/Downloads is the wrong answer. mkdir -p ~/.hookova/mcp cd ~/.hookova/mcp curl -fsSLO https://www.hookova.com/hookova-mcp.zip unzip -oq hookova-mcp.zip && rm hookova-mcp.zip bun install bun link export PATH="$(bun pm bin -g):$PATH" bun link installs both hookova and hokova. Add the export line above to your shell profile for future terminals. For Windows, add the directory from bun pm bin -g to your user Path and open a new terminal instead of running export. Run hookova --help for all shortcuts. The server files land — cli.ts, index.ts, core.ts, package.json, tsconfig.json, README.md, modules/, skills/ — and `bun install` fetches the two dependencies they need (the MCP SDK and zod). Nothing is compiled. Nothing is left running: the client starts the process when it wants the tools and stops it afterwards. ## 2. Register it with the client Claude Code, one command. The $HOME here is expanded by the shell before the config is written, which is the point — the config needs an absolute path and will not expand ~ itself. claude mcp add hookova --scope user -- bun "$HOME/.hookova/mcp/index.ts" --scope user makes it available in every project. Drop it to register for this project only. Already holding a token? Hand it over in the same command and skip step 4: claude mcp add hookova --scope user \ --env HOOKOVA_TOKEN=eyJ… \ -- bun "$HOME/.hookova/mcp/index.ts" Any other MCP client — the Claude desktop app (claude_desktop_config.json), Cursor (.cursor/mcp.json), most editor integrations — wants the same three facts as JSON: { "mcpServers": { "hookova": { "command": "bun", "args": ["/Users/you/.hookova/mcp/index.ts"], "env": { "HOOKOVA_TOKEN": "eyJ…" } } } } Both paths must be absolute, ~ included nowhere. For a desktop app, make "command" absolute too — /opt/homebrew/bin/bun, or whatever `command -v bun` prints. A GUI application does not inherit your shell's PATH, and that is the single most common reason a server registers cleanly and then lists no tools at all. ## 3. Restart the client The tool list is read once, at startup. Until the client restarts, nothing above has taken effect. In Claude Code: end the session, start a new one, and run /mcp — it should list hookova with forty-five tools. An assistant that just installed this does not have to stop here. Every tool also runs from the shell, through the same server, with no restart and no registration: hookova tools hookova status hookova guide '{"projectId":""}' Arguments are one JSON object, checked against the tool's schema; the answer is printed and a failed call exits 1. `hookova login` is the one that waits: it prints the approval URL, opens it, and keeps listening until it is approved or the five-minute session lapses — give it a long timeout. Keep using this until the next session, where the tools appear natively. ## 4. Sign in With no token, every tool answers "Sign in to save." The way out does not involve editing config or restarting anything a second time. Ask for connect() — in words, not JSON: "connect me to Hookova" From a terminal, run: hookova login It opens a one-shot listener on 127.0.0.1 and hands back a link. Open the link, approve the account in the browser, and the page posts the token straight back to this machine — the same loopback sign-in that gh auth login uses. Call connect again to wait for the approval; the link is good for five minutes and for one use. Chrome or Edge: Safari will not let an https page reach 127.0.0.1, so the hand-off cannot complete there. Prefer it to everything below. It works for Google-linked accounts, and the token never passes through the conversation, so it is never written into a transcript. sign_in is the manual alternative, for a token you already have in hand: "sign in to Hookova with this token: eyJ…" Either way the token is verified against the API before it is kept, saved to ~/.hookova/mcp.json at mode 0600 so the next run starts signed in, and never echoed back. Add remember: false to keep it to this session only. Then confirm with auth_status — "am I signed in to Hookova?" — which answers with the account, the plan, credits left, today's remaining save allowance, and which of the three places the token came from. ## TOKENS Two shapes work, and both last 30 days. Generated in the app, for any account: sign in at www.hookova.com, open Connect to My AI, and press Copy prompt. This creates a token and copies it with the install instructions. Paste into your coding assistant to configure the client. For manual configuration, copy HOOKOVA_TOKEN from the setup block. Google accounts work too. Minted over curl, for an account with a password: curl -s https://www.hookova.com/api/auth/token \ -H 'content-type: application/json' \ -d '{"email":"you@example.com","password":"…"}' | jq -r .token The session cookie also still works as a bearer — sign in, DevTools → Application → Cookies, copy __Secure-authjs.session-token, rejoining .0/.1 chunks in order — but the Settings panel exists so that nobody has to. The connect tool remains the best path where a browser can open. Prefer either of those to typing a password into a tool call. A password passed as a tool argument is written into the conversation transcript wherever the client stores it, and stays there. HOOKOVA_EMAIL + HOOKOVA_PASSWORD in the client's config do the same job — re-minting once on a 401, so a 30-day expiry becomes invisible — without a credential entering the chat. ## ENVIRONMENT HOOKOVA_TOKEN A minted token or a session cookie. Set here it wins at startup over a token saved by sign_in, so a stale one in the config silently overrides a fresh sign-in. Leave it out entirely and sign_in is the only source. HOOKOVA_EMAIL Optional pair. Re-mints a token once on a 401 — the fix for monthly HOOKOVA_PASSWORD re-pasting. Does nothing on a Google-linked account. HOOKOVA_API Defaults to https://www.hookova.com. Point it at http://localhost:3000 to work against a dev server. HOOKOVA_TOKEN_FILE Where sign_in saves its token. Defaults to ~/.hookova/mcp.json, mode 0600. ## THE FORTY-FIVE TOOLS connect(wait?, remember?) Sign in through the browser over loopback. The first call returns a link; call it again to wait for the approval. Prefer this to sign_in. auth_status() Signed in? As whom? From where? Plus plan, credits and today's save allowance. sign_in(token?, email?, password?, remember?) Verify a token and keep it. Prefer token. sign_out() Forget it here and on disk. Does not revoke it. save_link(url, title?) Any public URL, video or web page. Returns queued; title, synopsis, takeaways and category are written by a worker seconds later. list_saves(q?, tag?, limit?, cursor?) Search and browse, newest first, with every tag and its count. get_save(id) One save in full, plus whether a shot-by-shot analysis exists for the same URL. update_save(id, tags?, notes?, title?, liked?) tags REPLACES the whole list — read first, then write, or the rest are deleted. delete_save(id) Permanent, images included. No undo. export_saves(limit?) The library in bulk with notes and takeaways, capped at 100 by default. transcribe(url? | saveId?) Start a transcription of a TikTok, YouTube, Reels or RedNote video. SPENDS CREDITS (1 per saved clip; 1 per started 3 minutes for a link), charged on success only — confirm first. get_transcription(id?, text?) Status, then the timed transcript once done. Without id, the recent ones. list_projects() Every board: id, name, brief, how many saves are pinned. The way to find one by name. get_hook_guide(projectId, dir?, full?, overwrite?) A board as HOOK-GUIDE.md — brief, pinned saves, and each analysed clip's hook pattern shot by shot. With dir, writes the file and downloads the reference stills into dir/refs/. Free. generate_image(prompt?, reference_image?, preset_id?, dir?, filename?) One image from Pop-Cam's model, saved as a PNG. A reference (local path or https link) keeps a character the same across shots. SPENDS 1 CREDIT per image, on success only — credits provided by Pop-Cam. Say the price first. make_promo_video(website?, product_name?, description?, style?, picture?) A finished 30-40 s vertical promotion video from a product brief (Automated Content), ready in about 20 minutes. It claims only what description says. SPENDS 10 CREDITS, refunded automatically if it fails. Say the price first. English only. list_promo_videos(id?, dir?) Those videos: queued (place in line), running (stage, %), done (MP4 and cover links valid two hours, a suggested caption) or error. With dir, saves each finished MP4 there. Free. list_publish_accounts() The social accounts connected on hookova.com/publish — id, platform, handle, and its group. Connecting one is a browser sign-in on the platform, not a tool. list_publish_groups() The user's groups of accounts (a brand, a client), each with its accounts, plus those in no group. create_publish_group(name, accountIds?) Make a group; the named accounts move into it. update_publish_group(group, name?, addAccountIds?, removeAccountIds?) Rename a group, or move accounts in or out of it. delete_publish_group(group) Delete a group. Its accounts stay connected. publish_post(files, caption, accountIds?, group?, platforms?, scheduledAt?, draft?, title?, youtubePrivacy?, tiktokPrivacy?) Upload one video or up to ten photos from this machine and post them, now, at an ISO time WITH an offset, or as a draft. Every connected account by default, or every one in a group. REALLY POSTS — confirm with the user first. list_posts(status?, group?) Drafts, scheduled, posting and done, with where each landed once the platforms have taken it. get_post(id) One post, with where it landed once it has gone out. update_post(id, caption?, title?, accountIds?, scheduledAt?, randomMinutes?, draft?) Edit a draft (it stays a draft) or a scheduled post (it keeps its time unless given one). Media stays. schedule_draft(id, scheduledAt?) Send a draft now or at a time. Really posts. cancel_post(id) Withdraw a scheduled post, or delete a draft. search_sounds(query, group?, limit?, max_seconds?) The free sound-effect library (~1,000 short MP3s), ranked: id, group, tags, length, MP3 url. No sign-in. list_sounds(group?, offset?, limit?) Browse the sounds in title order. list_sound_groups() The sixteen kinds of sound, each with a count. get_sound(id) One sound's row. download_sound(id, dir, filename?, overwrite?) Write one MP3 into dir; returns the path. download_sounds(ids, dir, overwrite?) The same for several. search_music(query?, mood?, use?, max_seconds?, min_seconds?, limit?) 1,442 royalty-free tracks, narrowed by mood, use and length. No sign-in. list_music(mood?, use?, offset?, limit?) Browse the tracks in title order. list_music_tags() The twelve moods and twenty-two uses. recommend_music(brief, limit?, max_seconds?, min_seconds?) Describe the video, get tracks ranked by fit. Leave out mixing notes ("no vocals"). Needs the sign-in. get_track(id) One track's row. download_track(id, dir, filename?, overwrite?) Write one MP3 into dir; returns the path. download_tracks(ids, dir, overwrite?) The same for several. list_luts(query?, group?) The free sRGB color LUTs from the photo editor, by name or family, each with its .cube url. get_lut(id) One LUT's row and .cube url. download_lut(id, output, overwrite?) Save one .cube to an explicit path. apply_lut(input, output, presetId? | lutPath?, intensity?, overwrite?) Grade a local photo or video with FFmpeg and ffprobe on PATH. Free, nothing uploaded, the original kept; PNG/JPG or H.264 MP4 out. At most 1 GB, 16 megapixels, 180 s. SDR only. ## THE HOOK GUIDE get_hook_guide is the board-to-HyperFrames bridge: the material for building the opening of the user's OWN video on the pattern of the clips they pinned. The skill that drives it end to end in Claude Code ships in the zip under skills/, but Claude Code only reads skills from ~/.claude/skills, so link it once: ln -sfn "$HOME/.hookova/mcp/skills/hook-from-project" "$HOME/.claude/skills/hook-from-project" Then, in a fresh directory: "/hook-from-project ". It lists the boards, runs hyperframes init, writes the guide and the stills into the project, and hands the build to the hyperframes skills (npx hyperframes skills update). Nothing from the source clips is reused — the guide says so in its own text, and the skill repeats it. ## TROUBLESHOOTING The client lists no tools. The command could not run. Check that the path to index.ts is absolute and that bun is on the PATH the client uses — for a GUI client, that means the absolute path to bun. Cannot find package '@modelcontextprotocol/sdk' `bun install` was not run in the unzipped folder. cd to the folder holding index.ts and run it there. Every tool answers "Sign in to save." Ask for auth_status. It says whether a token is present at all, why it was refused, and which of the three places it came from. Usually the fix is sign_in with a fresh token. sign_in worked, but the next session is signed out. Either it ran with remember: false, or HOOKOVA_TOKEN is set in the client's config — the environment variable wins at startup. Remove it there and the saved sign-in takes over. A save comes back with no title or synopsis. Expected. save_link returns as soon as the row exists; the worker fills in the rest a few seconds later. Call get_save again. "Daily save limit reached." The allowance is per account and shared with the iOS app and the Chrome extension. There is no separate MCP quota. It resets daily. ## UPDATE / UNINSTALL Update — run hookova update (or hokova update). It downloads the latest release, installs dependencies and verifies it before replacing the installed files. Your sign-in is preserved. The next CLI command uses the update; restart running MCP clients to load it. Older installations without the command: re-run step 1 once. Source checkouts use git. Uninstall: cd ~/.hookova/mcp && bun unlink claude mcp remove hookova rm -rf ~/.hookova/mcp ~/.hookova/mcp.json Removing the token file is not revocation. Nothing here can cancel a token; it stays valid until its 30 days are up, so treat one that has leaked as still live. ## WHAT IT CANNOT DO - No starting an analysis. Shot-by-shot breakdowns are run in the web app; get_save reports whether one exists for a saved URL, and get_hook_guide reads the finished ones on a board. - No images or video in answers. Both are auth-gated URLs a model cannot open, so they are dropped rather than handed back as links that 401. The one exception is on disk: get_hook_guide with a dir writes the reference stills into dir/refs/ itself. - No separate quota. Saves here draw on the same daily allowance as everywhere else. - One account per install. For the hosted version with OAuth sign-in, see the top of this file. # Written for a person instead: https://www.hookova.com/guides/mcp-server