# Hookova MCP server — install runbook
#
# Seventeen tools that hand an assistant one Hookova account, in four modules: sign in; save a
# link, search what you saved, read one back, retag it, delete it, export the lot; read a project
# board as a hook guide for HyperFrames; and post a video or photos to the connected YouTube,
# TikTok, Instagram, Facebook and X accounts, now or at a time. It is a local stdio server —
# a few TypeScript files run by Bun on this machine, holding one token. Nothing is hosted, and
# no Hookova process watches the conversation.
#
# 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. Then use Publish to upload, draft, schedule, or post finished media to connected accounts. The Hookova MCP server does not render videos.
Tools: list_projects, get_hook_guide, list_publish_accounts, publish_post, list_posts, schedule_draft, cancel_post

### Tools & Assets
Transcribe Video is available in the app. Sound Effect Library and Music Library have separate MCP servers, with setup on /sound-effects and /music. Subtitle Library is coming soon. These tools are not part of the seventeen-tool Hookova server.
No tools in this server.

### 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. 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 analysis credit.


## 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 seventeen 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":"<id>"}'

  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, analysis 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 SEVENTEEN 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.
  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.
  list_publish_accounts()                      The social accounts connected on hookova.com/publish
                                               — id, platform, handle. Connecting one is a browser
                                               sign-in on the platform, not a tool.
  publish_post(files, caption, accountIds?, 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. REALLY POSTS — confirm with the user first.
  list_posts(status?)                          Drafts, scheduled, posting and done, with where each
                                               landed once the platforms have taken it.
  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.


## 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 <board name>". 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.
  - Local only. Stdio, one process, one token, one account. There is no hosted OAuth version.

# Written for a person instead: https://www.hookova.com/guides/mcp-server