# Hookova MCP server — install runbook
#
# Nine tools that hand an assistant one Hookova account's save library: save a link, search what
# you saved, read one back, retag it, delete it, export the lot. It is a local stdio server —
# one TypeScript file 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 and ask them for a token. Never ask for their password, and never put one in a tool
# argument — see TOKENS below for why.


## 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

  Four files land — index.ts, package.json, tsconfig.json, README.md — 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 ten tools.


## 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"

  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 is the only self-service route for a Google-linked account,
  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.

  Minted, 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

  Session cookie, for a Google-linked account done by hand — those have no password, so there is
  nothing to mint with. Sign in at www.hookova.com, open DevTools →
  Application → Cookies, and copy the value of __Secure-authjs.session-token. If the browser has
  split it into .0, .1 and so on, join those values in order with nothing between them. The
  connect tool exists so that nobody has to do this; it is documented because a headless machine
  with no browser still can't run it.

  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 TEN 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.


## 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 — re-run step 1. It overwrites in place, and nothing about the registration changes.
  Uninstall:

    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 analysis. Shot-by-shot video breakdowns stay in the web app; get_save reports whether one
    already exists for a saved URL.
  - No images or video. Both are auth-gated URLs a model cannot open, so they are dropped rather
    than handed back as links that 401.
  - 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